@aiquants/virtualscroll 3.7.1 → 3.8.1

package/CHANGELOG.md

@@ -2,6 +2,122 @@
 
 All notable changes to `@aiquants/virtualscroll` are documented here.
 
+## 3.8.1 (2026-10-03)
+
+### Fixed
+
+- **マウントのたびに一覧をもう一度描いていた**: 3.8.0 の装置の画素への揃えは、比をラッパーの取り付け (React の
+  確定の段) で状態へ確定していた。比が未定 (`null`) から比へ変わるこの更新のため、クライアントでのマウントの
+  たびに paint の前の同期の描き直し (React の Profiler では段階 `nested-update` の確定) が 1 回足されていた。
+  描き直すのは `VirtualScroll` 本体とペインで、React はその前に確定の passive effect も流す (実測でマウント
+  1 回あたり約 0.8〜1.4 ms、マウントの 4〜8 %)。行が 0 件からまた行を持つときのラッパーの付け直しでも同じ
+  描き直しが起きていた。ポップアップを開くたびに一覧をマウントするホストでは、開く操作ごとの確定が 1 回
+  増えていた。
+- **比は描画の中で読み、取り付けは確かめるだけにする**: 平行移動を揃える比はラッパーを描く部品が描画の中で
+  読む。取り付けの前は React を実行しているページのウィンドウを描くウィンドウと見込み、取り付けがラッパーの
+  文書のウィンドウと突き合わせる。自分のウィンドウの文書に描いた一覧は最初の確定から揃った値で描き、確定の段の
+  描き直しは起きない (マウントでも行 0 件からの付け直しでも `nested-update` は 0 回)。iframe や別ウィンドウの
+  文書に描いた一覧は、取り付けでそのウィンドウの比へ切り替えて paint の前に 1 回だけ同期で描き直す (3.8.0 と
+  同じく、見込みの比で揃えた値は描かれない)。ブラウザの拡大縮小や密度の違う画面への移動は従来どおり
+  `(resolution: <比>dppx)` のメディアクエリで追い、確定の段の外の通常の更新 1 回で揃え直す。サーバー描画の
+  HTML は厳密値のままで、ハイドレーションも厳密値で描くので不一致は報告されず、ハイドレーションの直後に揃えた
+  値へ置き換わる。ウィンドウを持たない文書へ描くとラッパーの取り付けで `Error` を投げるのも従来どおり。描かれる
+  値と公開 API は変わらない。
+- **テスト**: `VirtualScroll.spec.ts` +4 と 2 件の強化。`React.Profiler` で確定ごとの段階とその確定の時点の
+  transform を記録し、自分のウィンドウの文書へのマウントが比 1.25 でも最初の確定から格子上にあり
+  `nested-update` が無いこと、マウントの後の行 0 件 → 1000 件の付け直しの区間に `nested-update` が無く
+  付け直した確定から格子上にあること、比の変化は `update` の確定 1 回で揃え直すこと、`renderToString` は
+  厳密値を書き比 1.25 での `hydrateRoot` は不一致を報告せずハイドレーションの直後に揃え直すことを固定する
+  (新規 4 件)。act を使わない `flushSync` の行は確定が `mount` 1 回だけであることを、iframe の行は見込みの
+  ウィンドウからの切り替えが `nested-update` 1 回でその確定が iframe の比で揃っていることを足した。修正前の
+  ソースでは 3 件 (マウント・付け直し・`flushSync`) が red。vitest 1,030 件 / 53 ファイル (単体 999 + 統合 31。
+  2026-10-03 の `vitest run --maxWorkers=2` 1 回の全数実測で、すべて通りスキップ 0)。
+
+## 3.8.0 (2026-10-03)
+
+### Added
+
+- **スクロールバー矢印を Tab 順から外す `enableArrowButtonTabStops`**: 矢印ボタン 2 個を Tab の止まり先に
+  するかどうか (既定 `true` = 従来どおり)。行のロービングフォーカス (矢印 / Page / Home / End) やグリッドの
+  キーボードモデルのように、ホストがキーボードスクロールを自前で持つ場合に `false` を指定すると両矢印が
+  `tabIndex={-1}` になり、バー 1 本あたり 2 個の冗長な Tab の止まり先が消える (ネイティブのスクロールバーも
+  Tab の止まり先にならない)。変わるのは `tabIndex` だけで、ポインタ押下と長押しリピート・アクセシブルネーム・
+  スクリプトからフォーカスした矢印の Enter / Space は維持する。矢印は `role="scrollbar"` の要素の子孫で、
+  ARIA 1.2 はその子を presentational とするため、支援技術が矢印を独立したボタンとして示すかどうかは
+  ブラウザ次第 (Chromium は示し、バー全体を 1 つの操作部品として示すブラウザもある) — パッケージはそこを
+  約束しない。既定を `true` に据え置くのは、ホスト側のモデルが無ければ矢印が Tab で届く唯一のスクロール
+  操作部品だから (ペインは transform で動きネイティブのスクロール領域を持たず、行も Tab の止まり先ではない)。
+  矢印が無効な間 (`enableArrowButtons: false` またはスクロール不要) は効果なし。同じ名前と意味で全入口に
+  置いた: `ScrollBar` / `ScrollPane` の props と、`VirtualScroll` / `VirtualGrid` の `scrollBarOptions`
+  (グリッドは縦・横の両バーへ適用)。
+- **テスト**: 単体 `arrowButtonTabStops.spec.tsx` 24 件 (新規。4 入口それぞれで、未指定と `true` 明示の
+  `tabIndex=0` と Tab 経路、`false` の `tabIndex=-1` と Tab / Shift+Tab が止まらずに横切ること (user-event)、
+  名前付きのボタンのままで操作可能なこと、長押しリピート、スクリプトからフォーカスした矢印の
+  Enter / Space)、`VirtualGrid.spec.tsx` +7 (下記 Changed の両バー適用 5 件と `RangeError` の文面 2 件)、
+  `labels.spec.ts` +1 (`VIRTUAL_SCROLL_LABEL_KEYS` の列そのもの — 7 キーの件数と順序 — の固定。合成する側が
+  自分のキー表の先頭に連結して固定するため、キーの追加・並べ替えは破壊的変更になる)、
+  `shippedTextSelfContained.spec.ts` 51 件 (新規 — 下記 Changed)、`VirtualScroll.spec.ts` +12 (下記 Fixed の
+  装置の画素への揃え: 揃える関数の 4 件 — 比 1・1.25・1.5・2 で負・小数の入力が最も近い格子点へ揃うこと、代表値、
+  冪等、0 より大きい有限数でない比の `RangeError` — と、描画の 8 件 — 比 1 の 2440.5px が整数 px になること、
+  行の上端は端数のまま残ること、比 1.25・1.5・2 の格子、比の変化で揃え直して監視を新しい比で張り直すこと、
+  ラッパーの取り外しで監視を外し再取り付けで比を読み直すこと、iframe に描いた一覧はそのウィンドウの比を読むこと、
+  ウィンドウの無い文書で `Error` を投げること、act を使わない `flushSync` の描画でも戻った時点で揃っていること)。
+  vitest 1,026 件 / 53 ファイル (単体 995 + 統合 31。3.7.1 の取り込み後、2026-10-03 の `vitest run --maxWorkers=1` 1 回の全数実測で、
+  すべて通りスキップ 0)。
+
+### Changed
+
+- **`VirtualGrid` の横バーも `scrollBarOptions` のバー固有メンバーに従う**: `enableThumbDrag` /
+  `enableTrackClick` / `enableArrowButtons` (と新設の `enableArrowButtonTabStops`) を縦バーと同じく横バーへも
+  適用する。従来は横バーへ効くのが `width` / `tapScrollCircleOptions` だけで、これらを指定しても縦バーしか
+  変わらなかった (仕様書に既知の制約として記録していたもの)。1 つの設定がグリッドの片側だけに効く状態を
+  無くすための変更で、`tapScrollCircleOptions` は統合 2 軸サークル、`renderThumbOverlay` (可視行
+  インデックスを受け取る) と `enableScrollToTopBottomButtons` は行軸の機能として内包 `VirtualScroll` 専用のまま。
+- **公開の流れで tarball の漏洩検査を必ず通す**: `publish:patch` / `publish:minor` / `publish:major` は
+  typecheck → test → 漏洩検査 (`check-publish-leaks.mjs` — 自分で `pnpm pack` を行い、その tarball そのものを検査する)
+  → 版上げ → 公開 の順に、素の `pnpm publish` が起動する `prepublishOnly` は漏洩検査だけを走らせる。`pnpm pack` は
+  `prepare` (= ビルド) を走らせるため、検査する tarball は常にビルドしたての成果物で、公開の入口が二度ビルドすることはない。
+  検出が 1 件でもあれば版上げの前に止まる。配線は単体 `publishLeakGuard.spec.ts` 7 件 (新規) が固定する。
+  あわせて、同梱の README・CHANGELOG・`src/VirtualGrid.tsx` の注釈が参照していた、tarball に含まれない
+  設計文書への参照 (3.7.0 の tarball で検査が検出した 4 件) を、参照先が決めていた内容 (`VirtualGrid` の
+  有界化契約と、バーごとのタップサークルを抑止する理由) の記述へ置き換えた。
+- **同梱の文章を単独で読めるようにする**: `VirtualGrid` の `getRowHeight` / `getColWidth` が契約外の値を
+  返したときの `RangeError` は、読めない設計文書の節を示す代わりに、許容範囲と従い方と上限の理由を
+  自分で述べる: `[VirtualGrid] getColWidth(3) returned 262145 — must be an integer in [0, 262144] (0 = hidden).
+  Round fractional sizes to whole pixels and split content larger than 262144 px across several columns: a larger
+  track could push cell positions past the 2^25 px layout-coordinate limit of browsers.` (行は `rows`)。
+  あわせて README・CHANGELOG・型宣言 (`.d.ts` に載る docstring) から、tarball に含まれない文書への参照
+  (`docs/specs` などのパス、ADR 番号、設計文書の節番号 (§)、変異台帳の ID) を除き、参照先が決めて
+  いた内容の記述へ置き換えた (例: `VirtualGrid` が意図的に持たない行側メンバーの一覧、`MAX_RENDERED_CELLS`
+  が賄う画面の大きさ)。実装のコメントには設計文書の節への参照が素の節記号と題名の形で残る (ADR 番号、
+  設計・実装プランに続く節記号、リポジトリの `docs` の下の階層と `.agents`・`.worktrees` へのパスは、下記の
+  spec が同梱の全ファイルで拒否するため、コメントにも残さない)。単体 `shippedTextSelfContained.spec.ts` (新規)
+  は同梱物を `package.json` の `files` から導出し (`dist`・spec を除く `src`・README・CHANGELOG・LICENSE と
+  `package.json`)、本パッケージ独自の文書参照の規則 (ADR 番号、設計・実装プランに続く節記号、URL の一部では
+  ない `docs` の下の階層と `.agents`・`.worktrees` へのパス。規則は spec の中で定義し、モノレポの漏洩ガードの
+  規則ファイルは読まない) を、全パスと全ファイルの全文へコメントも含め、エスケープを復号した形にも当てる。
+  読み手向けのより厳しい規則 (数字の続く節記号、設計文書を題名で指すこと、変異台帳の ID) は、README・
+  CHANGELOG・型宣言・sourcemap (対応表 `mappings` を除く)・スタイルシート (コメントを除く) と、コードの
+  文字列・テンプレート・JSX の文字へ当てる。検出は `ファイル:行: [規則] "一致"` の一覧で示し、`files` の
+  項目が何にも一致しなければ (ビルド前の `dist` など) 名前を示して失敗する。
+
+### Fixed
+
+- **行ラッパーの平行移動を装置の画素へ揃える**: 行を包むラッパーは自前の合成層 (`will-change: transform`) を
+  `transform: translateY(…)` で動かす。その量がスクロール位置の端数 (トラックパッドや慣性の移動量・中央揃え・
+  端数の行の高さやインセット) をそのまま持つと、ブラウザは層全体を再標本化する。実画面ではペイン位置 2440.5px で
+  2px の輪郭・2px の隙間・2px の輪が 3+1+3 行に滲み (下辺では隙間が消え)、文字もぼけた。平行移動は一覧を描く
+  ウィンドウの装置の画素の格子へ揃える (`Math.round(量 × devicePixelRatio) / devicePixelRatio`。比 1 では整数 px、
+  1.25 では 0.8px、1.5 では 2/3px、2 では 0.5px の刻み)。比はラッパーの文書のウィンドウ (iframe や別ウィンドウに
+  描いた一覧ではそのウィンドウ) からラッパーの取り付け時に読み、ブラウザの拡大縮小や密度の違う画面への移動で
+  変わると `(resolution: <比>dppx)` のメディアクエリで読み直す。揃えるのはラッパーの平行移動だけで、行の位置
+  (層の中の端数の位置は描画が画素へ揃える) と、`onScroll` / `onRangeChange` / `getScrollPosition()` /
+  `getScrollAnchor()` が示す位置は厳密値のまま (見える位置のずれは最大で半装置画素)。`VirtualGrid` の行も
+  同じラッパーで描くので縦に揃う。サーバー描画の HTML は厳密値を持ち (サーバーに画面は無い)、ハイドレーションで
+  揃えた値に置き換わる。クライアントでのマウントは最初の paint の前に比を確定する。ウィンドウを持たない文書
+  (`document.implementation.createHTMLDocument()` で作った文書など) へ描くと、ラッパーの取り付けで `Error` を
+  投げる (描かれない文書には揃える比が無い)。
+
 ## 3.7.1 (2026-10-01)
 
 ### Fixed
@@ -92,13 +208,13 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   単調時の 56%。x は `hxRef` 単一書き手のため無事)。修正は**軸別位置権威の x 側への整列**:
   `getVy` を埋め込みハンドル `getScrollPosition()` (= `applyVy` の `scrollBy` が updater を解決する
   ペイン内部 ref と同一権威) の読みへ変更 — 「各軸の `getPos` は適用シームと同一権威を読む」を
-  ドライバ契約として登記 (グリッド仕様 §3.6 ADR-31 行 / MV-XY38-39)。`applyVy`・x 経路・
+  ドライバ契約とした。`applyVy`・x 経路・
   `computeTapScrollVelocity`・フックのループ意味論はバイト不変。
 - **デモ / ゲート**: エンジンデモに `/grid-tap` ルートを新設 (VirtualGrid + 統合サークル)。
   実ブラウザ E2E `grid-tap-scroll.spec.ts` (ページ内 rAF サンプラーで純 x / 純 y 1 秒保持の
   フレーム単調性 + 前進下限) と、決定的 rAF ハーネスの配線単体ゲート
   `gridTapAxisAuthority.spec.tsx` 3 件 (純 y / 斜め xy / 純 x の毎フレーム一様前進 —
-  鏡像退行変異 MV-XY38/39 で red 実証) を追加。単体 819 / 819 (46 ファイル)。
+  y の読みを鏡像へ戻す変異 2 本で red を実証) を追加。単体 819 / 819 (46 ファイル)。
 
 ## 3.6.0 (2026-09-18)
 
@@ -110,15 +226,15 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   帯幅非依存・凍結トグル不変)、**既定オフセットは両軸 −200** (到達性導出 — バー既定 −80/0 では
   ない)。opt-out は従来どおり `tapScrollCircleOptions: { enabled: false }` — 今後は**唯一の
   サークルを殺す**。封鎖コンテンツ面積は半減 (40 px ディスク 1 枚)。既定 ON の挙動置換を
-  **minor** とする判断は ADR-32 登記: 置換対象が出荷済み欠陥・再解釈フィールド
+  **minor** とした理由: 置換対象が出荷済み欠陥・再解釈フィールド
   (`offsetX`/`offsetY` — バー相対 → コーナー相対) への in-repo 依存ゼロ・型削除ゼロ (いずれか
   1 つでも崩れていれば 4.0.0 だった)。
 - **速度則**: 方向余弦分解 `v = (s_x(r)·ox/r, s_y(r)·oy/r)` — `s_a` は無改造
-  `computeTapScrollSpeed` の軸別評価 (純軸ドラッグは各バー則と画素法則恒等 = T1)。新規純関数
+  `computeTapScrollSpeed` の軸別評価 (純軸ドラッグは各バーの速度則と画素単位で恒等)。新規純関数
   `computeTapScrollVelocity` + 型 `TapScrollVelocityInput` / `TapScrollAxisSpeedParams` を
   **バレル export ×3**。`TapScrollCircle.axis` は `"x" | "y" | "xy"` の射影部分空間へ一般化
   (既定 `"y"` 不変・state 型不変 — `"xy"` の `direction` は径方向係合 `{0, 1}`)。
-- **登記デルタ (グリッド仕様 §3.6 の一覧が正典)**: キャンセルイベント無条件リセット (旧: 縦は
+- **バーのタップループとの挙動差**: キャンセルイベント無条件リセット (旧: 縦は
   paneId フィルタ → 一様に無条件 = 厳密 fail-closed) / 片軸境界はループ非停止・境界フラグ毎
   フレーム (反転で同一保持中に端から退却) / 軸上ピンの純軸ドラッグはループをパーク (角度付き
   pointermove で再開) / pendingColAnchor は**適用済み** hx デルタのみで解除 (バーの要求時規則
@@ -128,8 +244,7 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   意図縦 ⇒ 交差 829 px/s (2 s で ≈ 8+ 列 @200 px 列)、意図横 ⇒ 交差 1,533 px/s (2 s で
   ≈ **96 行** @32 px 行)。受入閾値 (タッチ実機・クローズドループ): 中央値 ≤ 1 列 (意図縦) /
   ≤ 6 行 (意図横) — 超過時は連続リマップ `φ_ε(θ) = θ − ε·sin 4θ` を 3.6.0 既定として出荷する
-  事前コミット。異方性下ではコンテンツ速度角 ≠ ドラッグ角 (全手掛かりはドラッグ角を表示 —
-  登記)。遮蔽 / 到達性の閾値表はグリッド仕様 §3.6。
+  事前コミット。異方性下ではコンテンツ速度角 ≠ ドラッグ角 (全手掛かりはドラッグ角を表示)。
 - **`axis="x"` の引き transform 修正**: `translateY` → `translateX` (「右ドラッグで下へ動く」
   出荷済み quirk — 裸バー opt-in 経由でのみ到達・in-repo 消費者ゼロ)。`"y"` はバイト恒等。
 - **forced-colors**: `.aqvs-tap-scroll-circle` へパッケージ初の `forced-colors: active` 輪郭
@@ -144,26 +259,26 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   `stretchMainSize` (縦バー限定でインライン主軸寸をスキップ — 横バーは stretch が主軸を寸法
   決めできないため書込み維持) を `ScrollPane` が `isSelfMeasuringViewport` で結線。幾何は
   `viewportSize` の数値由来で無傷。回帰ゲート = 実 Chromium ラダー E2E
-  (800→1300→800→600→1000 双方向回復)。ScrollPane 仕様 §2.5 に機構を登記。
-- 単体 815 / 815 (45 ファイル) 全緑・変異台帳 MV-XY 37 行 + MV-SM 3 行 (物理 43 変異) 全 red 実測。
+  (800→1300→800→600→1000 双方向回復)。
+- 単体 815 / 815 (45 ファイル) 全緑・変異 43 本すべての red を実測。
 
 ## 3.5.0 (2026-09-14)
 
 - **新機能 — `VirtualGrid` の両軸末尾凍結 (`frozenTrailingCols` / `frozenTrailingRows`)**:
-  末尾凍結はエンジン機能 (ADR-18 — route A)。列側は幅減算 + 右クリップ — スクロール帯幅を
+  末尾凍結はエンジン側の機能。列側は幅減算 + 右クリップ — スクロール帯幅を
   `viewport − W_F − W_T` へ一般化し (`scrollBandWidthRef` の単一 ref 源)、末尾セルは右アンカー
   クリップ `.aqvs-grid-row-trailing` / `-inner` の**帯ローカル left** で描画する (アンカー機構の
   外 — 先頭帯の鏡像)。行側は `.aqvs-grid-main` の**下**の第 2 帯外バンド `.aqvs-grid-trailing-rows`
   (クリップ高 = H_T_vis インライン、inner は木高 H_T の bottom 定着 — 帯上端 = extent − H_T_vis
   が全構成で成立)。帯行は `renderRow` 逐語再利用で 4 象限コーナー全種が無償成立。複合帯の
-  優先順位は LEADING > TRAILING > MIDDLE (ADR-19): 中帯が最初に潰れ (`bandWidth ≤ 0` は正準空窓
+  優先順位は LEADING > TRAILING > MIDDLE: 中帯が最初に潰れ (`bandWidth ≤ 0` は正準空窓
   start > end)、末尾が 2 番目 (CSS `max()` 左端 / bottom 定着 inner)、可視クリップの単一情報源は
   `trailingVisibleSize` (消費先はテンプレート高 / hbar `paddingRight` / `getFrozenSize` の vis
   export の 3 点ちょうど)。
 - **契約**: 両 props は [0, `MAX_FROZEN_TRAILING_COLS` / `MAX_FROZEN_TRAILING_ROWS` = 128] の整数
-  fail-fast (RangeError)・動的クランプは `min(T, count − 先頭実効)` で**先頭がカウント空間で勝つ**
-  (ADR-19-1)。**登記済み帰結**: 先頭 + 末尾の帯寸がビューポートを超えるとき、隠れた末尾セルは
-  どのスクロール位置でも可視化できない (文書化されたクランプ — `scrollToCell` の末尾 no-op は
+  fail-fast (RangeError)・動的クランプは `min(T, count − 先頭実効)` で**先頭がカウント空間で勝つ**。
+  **文書化した帰結**: 先頭 + 末尾の帯寸がビューポートを超えるとき、隠れた末尾セルはどの
+  スクロール位置でも可視化できない (文書化されたクランプ — `scrollToCell` の末尾 no-op は
   そこでも正確)。T = 0 は DOM 構造・インライン属性までバイト恒等 (F = 0 / R = 0 恒等の双子)。
   `scrollToCell` / `initialScrollAnchor` の末尾狙いは当該軸 no-op (列は既存アンカー残置)、
   `updateRowSize` / `focusRowAtIndex` は 3 分岐 (末尾帯行は `trailingRowEpoch` 繰上げ / 帯行 DOM
@@ -175,15 +290,15 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
 - **`--aqvs-grid-trailing-width`**: 新設のパッケージスコープ CSS 変数 (0px フォールバック)。
   T > 0 のときのみ書かれ T = 0 で除去される**単一書き手**規律。`.aqvs-grid-row-scroll` の
   `right` は `var(--aqvs-grid-trailing-width, 0px)` へ差替え (T = 0 は計算結果までバイト恒等)。
-- **ADR-25 — `data-aqvs-frozen-row` の付与を F_eff > 0 へゲート分離**: 従来は凍結分岐と結合して
+- **`data-aqvs-frozen-row` の付与を F_eff > 0 へゲート分離**: 従来は凍結分岐と結合して
   いたため、末尾のみ (F = 0 ∧ T > 0) のグリッドが凍結列ゼロで全行に属性を出す嘘になるところ
   だった。class `aqvs-grid-row-frozen-host` は「横帯モード」の描画トレイトとして残る。既存構成
   (F > 0 / T = 0) への挙動変化ゼロ。
-- **ADR-23 — T の実行時変更は埋め込み VirtualScroll を再マウントしない**: `key` は R 専用のまま、
+- **T の実行時変更は埋め込み VirtualScroll を再マウントしない**: `key` は R 専用のまま、
   itemCount が**末尾**で伸縮するだけ (getItem / getItemKey / getItemHeight = i + R 不変)。視点は
   トグルを跨いで無償保存される。**保留アンカーの帰結 (文書化)**: T 増加で末尾帯入りする行を
   狙った保留行アンカーは最終スクロール行へクランプされる (itemCount 変化ごとの再ピン留め +
-  `sanitizeIndex` — 「保留アンカーは R 再マウントで死ぬ」の鏡像)。MV-TR-A1..A4 ゲートで実測確定
+  `sanitizeIndex` — 「保留アンカーは R 再マウントで死ぬ」の鏡像)。専用ゲート 4 件で実測確定
   (740/740 全緑)。
 
 ## 3.4.0 (2026-09-03)
@@ -196,7 +311,7 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   ゲートを `ScrollBar.spec.tsx` に追加 (695/695 全緑)。
 
 - **新機能 — `VirtualGrid` の凍結先頭行 (`frozenLeadingRows`)**: 帯外バンド + インデックス
-  シフト方式 (行凍結設計プラン §2)。凍結行 [0, R) はグリッド所有の `.aqvs-grid-frozen-rows`
+  シフト方式。凍結行 [0, R) はグリッド所有の `.aqvs-grid-frozen-rows`
   バンドとして pane の外 (上) に描画し、行本体は `renderRow` をそのまま再利用 — F > 0 の
   凍結セル構造 (静的セル / row-scroll クリップ / hx 残差 var) が帯行内でも成立し**凍結行 ×
   凍結列の 4 象限コーナーが無償で成立**。埋め込み VirtualScroll にはシフト済み行空間
@@ -233,14 +348,14 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   全行を再レンダーさせていた perf 欠陥の是正 (+R 挙動は不変)。(3) getScrollAnchor ハンドル
   docstring に縮退帯 null (H_F がビューポートを埋め itemCount 0 → null) を明記。
 - **検証**: 専用 spec `VirtualGridFrozenRows.spec.tsx` 19 (パッケージ 694/694、42 ファイル)
-  と変異 MV-FR30〜FR45 red 実測 (FR40 は ×2 変異とも red。getItemKey +R シフト撤去のみ
-  GT-2 として ⚠️ 等価登記 — 現状仕様 §5 台帳、全 102 変異 = 101 red + 1 ⚠️ 等価。
+  と変異 16 本の red 実測 (うち 1 本は 2 通りの変異とも red。getItemKey の +R シフト撤去だけは
+  観測上の等価変異として記録 — 全 102 変異 = 101 red + 1 等価。
   `VirtualGridFrozen.spec.tsx` の `getFrozenSize` deep-equal ピン 4 件も rows / height 込みへ
   更新)。
 
 ## 3.3.0 (単独未公開 — 3.4.0 に同梱して公開)
 
-- **新機能 — `VirtualGrid` の凍結先頭列 (`frozenLeadingCols`)**: 設計 §8 の 3 形状要件を実装。
+- **新機能 — `VirtualGrid` の凍結先頭列 (`frozenLeadingCols`)**: 次の 3 形状要件を実装。
   (a) スクロール帯の窓探索は木座標 W_F + hx 始まり (幅 0 凍結列の床クランプ込み)、(b) 残差は
   静的クリップ (`.aqvs-grid-row-scroll`) 内の inner が `calc(残差 − W_F)` で運ぶ (クリップと
   transform の分離は構造要件)、(c) 凍結帯はアンカー機構の外の静的 subtree (木絶対 left 直接
@@ -249,11 +364,10 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   **F = 0 は DOM 構造まで従来と恒等** (既存 648 テスト無変更 green)。契約: [0, 128] の整数
   fail-fast (`MAX_FROZEN_LEADING_COLS` 新 export)・colCount 超過は動的クランプ (全列凍結)・
   凍結列狙いの scrollToCell / initialScrollAnchor の x は no-op・`getFrozenSize()` ハンドル新設。
-  検証: 専用 spec 27 (パッケージ 675/675) + 変異 MV-FR1〜FR29 全 red 実測 (現状仕様 §5 台帳 —
-  R1 敵対レビューの実証欠陥 2 件 (全列凍結の両帯重複 / ヒール共有バッチの上書き非対称) と
-  実証穴 2 件 (帯ガード無ゲート / CSS 特異度) を封鎖済み)。publish 振付: 3.2.0 と 3.3.0 は
-  積層未リリースのため、版ラベル整合には凍結列コミットの親で 3.2.0 → HEAD で 3.3.0 の
-  2 段 publish が必要 (現状仕様 §8 の正準記録)。
+  検証: 専用 spec 27 (パッケージ 675/675) + 変異 29 本すべての red 実測 (R1 敵対レビューの
+  実証欠陥 2 件 (全列凍結の両帯重複 / ヒール共有バッチの上書き非対称) と実証穴 2 件 (帯ガード
+  無ゲート / CSS 特異度) を封鎖済み)。publish 振付: 3.2.0 と 3.3.0 は積層未リリースのため、
+  版ラベル整合には凍結列コミットの親で 3.2.0 → HEAD で 3.3.0 の 2 段 publish が必要。
 
 ## 3.2.0 (単独未公開 — 3.4.0 に同梱して公開)
 
@@ -269,14 +383,19 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   の消費者はグリッド所有 `.aqvs-grid-row` の translateX (ペイン構造クラスを侵さない)。ヘッダー
   同期は範囲通知 (`VirtualGridRange`) + 消費側の窓原点相対方式。行側パリティ引継ぎ:
   `horizontalKeyInputs` / `horizontalKeyStep` / `contentInsets` / `background` / `onRowFocus` /
-  `focusRowAtIndex` / `behaviorOptions.defaultColWidth` (全メンバー分類表は
-  `docs/specs/2026.09.01 [AI] virtualscroll-virtual-grid.md` §3.1 / §3.2)。設計正典:
-  `docs/plans/2026.09.01 [AI] virtualgrid-horizontal-axis-design-plan.md` (v6 認証済み)。
+  `focusRowAtIndex` / `behaviorOptions.defaultColWidth`。意図的に持たない行側メンバーは
+  `initialScrollIndex` / `initialScrollOffset` (`initialScrollAnchor` が唯一の口)・`onWheelHorizontal` /
+  `onPanHorizontal` (横軸はグリッドの所有)・ハンドルの `scrollToIndex` (`scrollToCell` が上位互換) /
+  `getFenwickTreeTotalHeight` / `getFenwickSize`。有界化契約 (両軸):
+  祖先スケール 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 まで成り立つ。
 - **シーム — `ScrollPane` / `VirtualScroll` に `onPanHorizontal`**: ポインタパン横成分の委譲
   (onWheelHorizontal のパン対・同符号・per-move 増分・押下時横 scale 除算)。指定時は横移動でも
   ドラッグが発動する。未指定の既存消費者への影響ゼロ。❗ 横軸を `Omit<>` で封じるラッパー
   (directory-tree) は 3.2.0 更新時に本シームを封印リストへ追加し (pass-through review)、
-  **select-box / daily-report の影響なし確認**も同時に行うこと (設計 §11)。
+  **select-box / daily-report の影響なし確認**も同時に行うこと。
 - **改修 — `ScrollBar` 横タップサークル**: `enableHorizontalTapCircle` (opt-in — 単体既定不変)
   で横バーにもタップスクロールサークルを描画。`TapScrollCircle` の方向・距離・デッドゾーン
   導出を軸パラメータ化 (`axis` prop)。
@@ -293,17 +412,17 @@ All notable changes to `@aiquants/virtualscroll` are documented here.
   アクセサ identity を再構築キーへ届くよう修正 (従来は構造的に不発)。`defaultColWidth` は実行時
   変更にも追随。liveRegion は行側契約へ整列 (既定 400ms・不正値は警告 + 無効化 — 黙示代替も変異で
   封止)。横タップサークルへ `itemCount = colCount` を自動配線しタップ速度の log10(colCount) 則
-  (設計 B7 対策) を実現、`tapScrollCircleOptions` も横バーへ透過。self-heal バーストは窓非依存の
-  「連続する非収束」計数 (解消は収束パスのみ — 窓端を動かす振幅の振動アクセサにも回避されず、
-  停止後はどの窓かでの収束 1 回で再武装。逐次の正当な治癒は誤認しない)。
+  を実現 (10^13 列ではサム 1 px ≈ 200 億列で、サムでは列を狙えないため)、`tapScrollCircleOptions` も
+  横バーへ透過。self-heal バーストは窓非依存の「連続する非収束」計数 (解消は収束パスのみ —
+  窓端を動かす振幅の振動アクセサにも回避されず、停止後はどの窓かでの収束 1 回で再武装。逐次の
+  正当な治癒は誤認しない)。
 - **品質**: vitest 648 / 648 = 単体 618 + 統合 30 (VirtualGrid 59 + 横シーム 10 + Fenwick baseValue 4
-  の新設ゲート込み)・変異 56 本 (MV-A〜MV-BD — アンカー / 残差 / 上限 / 打切り / clamp / パン符号・発動・scale /
+  の新設ゲート込み)・変異 56 本 (アンカー / 残差 / 上限 / 打切り / clamp / パン符号・発動・scale /
   タップ軸 / バー追従 / 幅エポック / 分母見積り / self-heal / 境界規約 / baseValue / contentProps
   持込 / 総幅同期 / 具現化計数 / リサイズ無効化 / 実測引継ぎ / identity 追随 / 暴走ガード /
   再ピン留め / 手動解除 / 同 tick 鮮度 / debounce 検証・黙示代替 / keyStep 透過 / overscan 15 化 /
   見積り基点 / 解除 3 サイト / 速度則配線 / 収束解消 / 蓄積撤去 / 停止恒久化 / tap オプション透過 /
-  非表示行スキップ / gBCR 計測復帰) 全 red 実測。台帳は
-  `docs/specs/2026.09.01 [AI] virtualscroll-virtual-grid.md` §5。
+  非表示行スキップ / gBCR 計測復帰) 全 red 実測。
 
 ## 3.1.1 (2026-08-28)
 
@@ -403,7 +522,7 @@ A-5 のうち**固定リピートタイマは実装を見送り**ました: 長
 ### Notes
 
 - デモに `/overscroll` (ページに縦あふれを持つ連鎖検証ルート) を追加。
-- ❗ E2E 作者向けの罠 (テスト仕様書 §6 に詳細): 離散的な合成ホイールを**ペインより上**のページ要素で
+- ❗ E2E 作者向けの罠: 離散的な合成ホイールを**ペインより上**のページ要素で
   打つと、compositor が先にページをスクロールし、イベント配送時の hit-test が「ずり上がってきた行」に
   当たって 1 ノッチがページとペインの両方へ入る (実測: listener 内の rect が移動済みの座標を示す)。
   実ジェスチャはスクロールラッチで保護される。陽性コントロールの打点は**ペインより下**に取ること。
@@ -446,7 +565,7 @@ A-5 のうち**固定リピートタイマは実装を見送り**ました: 長
 - 2.5.0 の既知の限界に「両 ref を layout effect へ移すとタップスクロールの走破が短くなる退行が実機
   E2E で出る」と記録していましたが、**8 回 x 3 系列の A/B/A 対照実験で反証されました**。当時観測した
   失敗は書き込み位置と無関係のコールドスタート負荷フレーク (rAF が ~10fps へ落ち、`deltaSeconds` が
-  100ms キャップに張り付いてサンプル数の前提が崩れる — テスト仕様書 §6.1 に記載済みの既知モード) で、
+  100ms キャップに張り付いてサンプル数の前提が崩れる既知のモード) で、
   render 本体書き込みの有無に関わらず同率 (6-7/8) で失敗します。「3 回失敗 → revert → 3 回成功」は
   負荷の時間的クラスタリングが生んだ錯覚でした。全 1,893 回のクランプ監査で committed 値と
   render 新値の食い違いは 0 件です。
@@ -549,7 +668,7 @@ A-5 のうち**固定リピートタイマは実装を見送り**ました: 長
 - 行は依然としてタブ順に入りません (`tabIndex={-1}`)。キーボードのみで横スクロールへ到達させたい消費側は
   `handle.focusItemAtIndex(0)` などでフォーカスの入口を用意してください (ロービングタブインデックスの
   導入は全消費側のタブ順を変えるため見送り)。デモ (`/horizontal`) にその実演ボタンを追加しました。
-- 既知の限界 (いずれも仕様書 §11.4 に記載): 行内でドラッグ選択/ダブルクリックすると選択が残り、それを
+- 既知の限界: 行内でドラッグ選択/ダブルクリックすると選択が残り、それを
   畳むキーボード手段が無いため `Shift + ←/→` が効かないままになる / Shadow DOM 内の選択は検出できない /
   横スクロールは支援技術へ何も伝わらない / 縦スクロールでフォーカス行が仮想化で消えるとフォーカスが
   `<body>` へ落ちる / 位置を量子化する消費側では `horizontalKeyStep` が量子未満だと 1px も動かない /

package/README.md

@@ -13,7 +13,7 @@ High-performance virtual scrolling component for React with variable item height
 - ↔️ **Horizontal Delegation**: Opt-in `onWheelHorizontal` hands horizontal wheel / trackpad (and shift+wheel) gestures to the parent — build frozen-column data grids
 - 🎨 **Customizable**: Flexible styling and theming options
 - 🌀 **Ultrafast Tap Scroll**: Adaptive tap scroll circle that scales speed up to 120× for massive datasets
-- ♿ **Accessibility opt-ins**: Escape row-return (`enableEscapeRowReturn`) and a screen-reader live region (`liveRegion`) announcing the visible range with your own wording
+- ♿ **Accessibility opt-ins**: Escape row-return (`enableEscapeRowReturn`), a screen-reader live region (`liveRegion`) announcing the visible range with your own wording, and scrollbar arrows out of the Tab order for apps with their own keyboard scrolling (`enableArrowButtonTabStops`)
 - 🌐 **Localization**: The built-in chrome strings (scrollbar arrow labels, scroll-to-edge pills, empty state) ship in English (default) and Japanese via `locale`, with per-key `labels` overrides. See [Localization](#localization)
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
 
@@ -135,6 +135,34 @@ the rendered row count and scrollability all derive from it, so all five would b
 spilling over the next element, a dead band at the bottom, an end you can never reach, a thumb that
 leaves the viewport, or a list that ignores the wheel entirely).
 
+## Device-pixel snapping
+
+The rows move inside one wrapper that is translated with `transform: translateY(…)` on its own compositor
+layer (`will-change: transform`). That translate is snapped to the device-pixel grid of the window the list
+is painted in, `Math.round(offset × devicePixelRatio) / devicePixelRatio`: whole CSS pixels at a ratio of 1,
+steps of 0.8 px at 1.25, 2/3 px at 1.5 and 0.5 px at 2. Fractional scroll positions (trackpad and inertia
+deltas, centred alignment, fractional row heights or insets) therefore never move the layer by a fraction of
+a device pixel. A layer moved by a fraction is resampled as a whole: 2 px borders, outlines, focus rings and
+the gaps between them smear across neighbouring pixel rows, and text blurs.
+
+- The ratio comes from the window of the list's own document, and it is read while the wrapper renders.
+  Before the wrapper is attached, the component expects the window of the page that runs React, and the
+  attach confirms it. A list rendered into its own window's document is therefore snapped in its first
+  commit, with no extra render. A list rendered into an iframe or a second window switches to that
+  window's ratio when the wrapper attaches, with one extra synchronous render before the browser paints.
+  The ratio is read again whenever it changes (browser zoom, or moving the window to a screen of another
+  density), through a `(resolution: <ratio>dppx)` media query.
+- Only the wrapper translate is snapped. Row positions inside it keep their exact values (the browser paints
+  fractional positions inside a layer on whole pixels already), and every position the component reports
+  (`onScroll`, `onRangeChange`, `getScrollPosition()`, `getScrollAnchor()`) stays exact. The rows are drawn
+  at most half a device pixel away from the exact scroll position. `VirtualGrid` rows are drawn by the same
+  wrapper, so they are snapped vertically as well.
+- Server-rendered HTML carries the exact offset, since there is no screen on the server. Hydration renders
+  the same exact offset, so it reports no mismatch, and the snapped offset replaces it right after hydration.
+- Rendering into a document without a window (for example one made with
+  `document.implementation.createHTMLDocument()`) throws when the wrapper attaches: nothing is painted there,
+  so there is no ratio to snap to.
+
 ## Horizontal Scrolling
 
 `VirtualScroll` virtualizes and scrolls the **vertical** axis only. To add a horizontal axis — e.g. a
@@ -327,6 +355,35 @@ itself has focus (an `Escape` on the row means whatever *you* decide — e.g. de
 does act it calls `preventDefault()` only and does not stop propagation, the same contract as the
 arrow keys.
 
+## Scrollbar arrows and the Tab order
+
+The scrollbar's two arrow buttons are Tab stops by default, because they are the only scrolling
+control a keyboard user can reach with Tab: the pane moves its content by transform (there is no
+native scroller for the browser to make focusable) and the rows are not Tab stops. Focus an arrow
+and Enter / Space scrolls one step.
+
+When your app already provides keyboard scrolling — roving focus with Arrow / Page / Home / End on
+the rows, a grid keyboard model — the arrows only add two redundant stops per bar. Take them out of
+the Tab order:
+
+```tsx
+<VirtualScroll
+    scrollBarOptions={{ enableArrowButtonTabStops: false }} // the rows own keyboard scrolling
+    ...
+/>
+```
+
+`false` sets `tabIndex={-1}` and changes nothing else: pointer presses and press-and-hold repeat keep
+working, the arrows keep their accessible names, and Enter / Space still scroll an arrow you focus
+from script — the position native scrollbars are in, which are never Tab stops either. What the
+package does not promise is that assistive technology lists the arrows as buttons of their own:
+they are descendants of the `role="scrollbar"` element, whose children ARIA 1.2 makes
+presentational. Chromium exposes them anyway; other browsers may present the whole bar as one
+control. The option has one name and one meaning everywhere: `ScrollBar` and `ScrollPane` props,
+and `scrollBarOptions` of `VirtualScroll` and `VirtualGrid` (the grid applies it to both of its
+bars). While the arrows are disabled (`enableArrowButtons: false`, or nothing to scroll) it has no
+effect — a disabled button is never focusable.
+
 ## Screen-reader live region
 
 Virtualization removes off-screen rows from the DOM, so a screen-reader user scrolling the list
@@ -440,8 +497,14 @@ trillion columns sit comfortably inside).
 </VirtualGrid>
 ```
 
-Contracts (see the design plan under `docs/plans/` for the full bounding theorem):
+Contracts:
 
+- Bounding contract (both axes): the anchored coordinates the grid writes to the DOM — cell and
+  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(z)`,
+  `ANCHOR_REBASE_DISTANCE` is 2^20 px and `windowSpan <= viewport + (2 × overscan + 2) × MAX_TRACK_SIZE`
+  is the rendered window. The next two contracts are its premises (the z ≈ 5.3 they yield assumes
+  a viewport of at most 2^13 px).
 - `getRowHeight` / `getColWidth` return integer px, `0` = hidden, `<= MAX_TRACK_SIZE`
   (2^18 px) — oversized tracks fail fast with a `RangeError` (a single unbounded track would
   pierce the measured browser layout wall at 2^25 px).
@@ -459,11 +522,18 @@ Contracts (see the design plan under `docs/plans/` for the full bounding theorem
 - Row-side parity carries: `horizontalKeyInputs` / `horizontalKeyStep` (arrow keys reach the
   grid-owned horizontal axis), `contentInsets`, `background`, `onRowFocus` /
   `focusRowAtIndex`, and `behaviorOptions.defaultColWidth` (explicit Fenwick baseValue — skips
-  width sampling). The full member-by-member classification lives in
-  `docs/specs/2026.09.01 [AI] virtualscroll-virtual-grid.md`.
+  width sampling). Deliberately not offered: `initialScrollIndex` / `initialScrollOffset` (use
+  `initialScrollAnchor`), `onWheelHorizontal` / `onPanHorizontal` (the grid owns its horizontal
+  axis and consumes those deltas itself), and on the handle `scrollToIndex` (use `scrollToCell`)
+  and `getFenwickTreeTotalHeight` / `getFenwickSize` (use `getContentSize` and the counts you pass).
 - `locale` / `labels` (see [Localization](#localization)) are forwarded to BOTH the embedded
   `VirtualScroll` (vertical arrows and the "No items" empty state shown for 0 rows, an all-frozen row
   set or a degenerate band) and the horizontal `ScrollBar` (left / right arrows).
+- `scrollBarOptions`: the bar-local members — `width`, `enableThumbDrag`, `enableTrackClick`,
+  `enableArrowButtons` and `enableArrowButtonTabStops` — apply to BOTH bars alike, so no setting
+  covers only half of the grid. `tapScrollCircleOptions` configures the single two-axis circle;
+  `renderThumbOverlay` (fed with visible row indices) and `enableScrollToTopBottomButtons` are
+  row-axis features of the embedded `VirtualScroll`.
 - Frozen leading columns (v3.3.0): `frozenLeadingCols` pins the first F columns as a static
   band OUTSIDE the anchor machinery (direct tree-absolute lefts; scroll cells live inside a
   static clip whose inner carries the `residual - W_F` origin-shift transform). Integer in
@@ -503,7 +573,7 @@ Contracts (see the design plan under `docs/plans/` for the full bounding theorem
   the tree height H_T). Band rows reuse the normal row renderer, so every corner of the
   3 x 3 region grid comes for free. Integers in `[0, MAX_FROZEN_TRAILING_COLS]` /
   `[0, MAX_FROZEN_TRAILING_ROWS]` (128) — `RangeError` otherwise; the dynamic clamp is
-  `min(T, count - effectiveLeading)`: the LEADING band wins the count space (ADR-19-1), and
+  `min(T, count - effectiveLeading)`: the LEADING band wins the count space, and
   when the leading + trailing extents exceed the viewport, occluded trailing cells cannot be
   scrolled into view (a documented clamp — `scrollToCell` / `initialScrollAnchor` targeting a
   trailing track stay no-ops on that axis, the column no-op leaving any armed column anchor in
@@ -629,6 +699,7 @@ exists in the DOM.
 | `enableThumbDrag` | `boolean` | Enable dragging the scrollbar thumb (default: true) |
 | `enableTrackClick` | `boolean` | Enable clicking the scrollbar track (default: true) |
 | `enableArrowButtons` | `boolean` | Enable arrow buttons on the scrollbar (default: true) |
+| `enableArrowButtonTabStops` | `boolean` | Keep the two arrow buttons in the Tab order (default: true). Set `false` when your app already owns keyboard scrolling of the list: the arrows then get `tabIndex={-1}` and stay pointer-operable and named. See [Scrollbar arrows and the Tab order](#scrollbar-arrows-and-the-tab-order) |
 | `enableScrollToTopBottomButtons` | `boolean` | Enable the auto-hiding Top/Bottom pills (texts from `labels.scrollToTop` / `labels.scrollToBottom`; default: false) |
 | `renderThumbOverlay` | `(props: ScrollBarThumbOverlayRenderProps) => ReactNode` | Render prop to anchor custom UI near the scrollbar thumb |
 | `tapScrollCircleOptions` | `ScrollBarTapCircleOptions` | Customization for the auxiliary tap scroll circle |

package/dist/ScrollBar.d.cts

@@ -80,6 +80,40 @@ export type ScrollBarProps = {
     enableTrackClick?: boolean;
     /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean;
+    /**
+     * Whether the two arrow buttons are Tab stops (default `true`).
+     *
+     * `false` renders both with `tabIndex={-1}`, which takes them out of the sequential focus order
+     * and changes nothing else: pointer presses and press-and-hold repeat, the accessible names and
+     * Enter / Space on an arrow focused from script all keep working. The arrows are descendants of
+     * the `role="scrollbar"` root, whose children ARIA 1.2 makes presentational, so whether assistive
+     * technology lists them as buttons of their own is the browser's choice (Chromium does); this
+     * option changes nothing about that. Set it to `false` when the host already owns keyboard
+     * scrolling of this viewport (roving row focus with Arrow / Page / Home / End, a grid keyboard
+     * model): the arrows then duplicate that path and cost every keyboard user two extra Tab presses
+     * per bar — native scrollbars are never Tab stops either. The default stays `true` because
+     * without such a host model the arrows are the only scrolling control a keyboard user can reach
+     * with Tab: `ScrollPane` / `VirtualScroll` move their content by transform, so there is no native
+     * scroller the browser could make focusable, and their rows are not Tab stops. No effect while
+     * the arrows are disabled (`enableArrowButtons: false`, or nothing to scroll) — a disabled button
+     * is never focusable.
+     *
+     * 矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。
+     *
+     * `false` は両方を `tabIndex={-1}` で描画し、順次フォーカス移動の順序から外すだけの指定。
+     * ポインタ押下と長押しリピート、アクセシブルネーム、スクリプトからフォーカスした矢印での
+     * Enter / Space はすべて維持。矢印は `role="scrollbar"` のルートの子孫で、ARIA 1.2 はその子を
+     * presentational とするため、支援技術が矢印を独立したボタンとして示すかどうかはブラウザの選択
+     * (Chromium は示す) であり、本オプションはそこに関与しない。ホストがこのビューポートのキーボード
+     * スクロールを既に持つ場合 (行のロービングフォーカスと矢印 / Page / Home / End、グリッドのキーボードモデル) に
+     * `false` を指定 — 矢印はその経路の重複となり、キーボード利用者にバー 1 本あたり 2 回の余分な Tab を
+     * 課すため (ネイティブのスクロールバーも Tab の止まり先にならない)。既定を `true` に据え置く理由は、
+     * ホスト側のモデルが無ければ矢印がキーボード利用者の Tab で届く唯一のスクロール操作部品であること
+     * (`ScrollPane` / `VirtualScroll` はコンテンツを transform で動かすため、ブラウザがフォーカス可能に
+     * できるネイティブのスクロール領域が無く、行も Tab の止まり先ではない)。矢印が無効な間
+     * (`enableArrowButtons: false` またはスクロール不要) は効果なし — disabled のボタンはそもそもフォーカス不能。
+     */
+    enableArrowButtonTabStops?: boolean;
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
     horizontal?: boolean;
     /**
@@ -266,5 +300,5 @@ export declare const computeAutoTapScrollMaxSpeedMultiplier: (itemCount?: number
  *
  * カスタムスクロールバーコンポーネント。
  */
-export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, enableHorizontalTapCircle, stretchMainSize, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, locale, labels, }: ScrollBarProps) => import("react").JSX.Element;
+export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, enableArrowButtonTabStops, horizontal, enableHorizontalTapCircle, stretchMainSize, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, locale, labels, }: ScrollBarProps) => import("react").JSX.Element;
 export {};

package/dist/ScrollBar.d.ts

@@ -80,6 +80,40 @@ export type ScrollBarProps = {
     enableTrackClick?: boolean;
     /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean;
+    /**
+     * Whether the two arrow buttons are Tab stops (default `true`).
+     *
+     * `false` renders both with `tabIndex={-1}`, which takes them out of the sequential focus order
+     * and changes nothing else: pointer presses and press-and-hold repeat, the accessible names and
+     * Enter / Space on an arrow focused from script all keep working. The arrows are descendants of
+     * the `role="scrollbar"` root, whose children ARIA 1.2 makes presentational, so whether assistive
+     * technology lists them as buttons of their own is the browser's choice (Chromium does); this
+     * option changes nothing about that. Set it to `false` when the host already owns keyboard
+     * scrolling of this viewport (roving row focus with Arrow / Page / Home / End, a grid keyboard
+     * model): the arrows then duplicate that path and cost every keyboard user two extra Tab presses
+     * per bar — native scrollbars are never Tab stops either. The default stays `true` because
+     * without such a host model the arrows are the only scrolling control a keyboard user can reach
+     * with Tab: `ScrollPane` / `VirtualScroll` move their content by transform, so there is no native
+     * scroller the browser could make focusable, and their rows are not Tab stops. No effect while
+     * the arrows are disabled (`enableArrowButtons: false`, or nothing to scroll) — a disabled button
+     * is never focusable.
+     *
+     * 矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。
+     *
+     * `false` は両方を `tabIndex={-1}` で描画し、順次フォーカス移動の順序から外すだけの指定。
+     * ポインタ押下と長押しリピート、アクセシブルネーム、スクリプトからフォーカスした矢印での
+     * Enter / Space はすべて維持。矢印は `role="scrollbar"` のルートの子孫で、ARIA 1.2 はその子を
+     * presentational とするため、支援技術が矢印を独立したボタンとして示すかどうかはブラウザの選択
+     * (Chromium は示す) であり、本オプションはそこに関与しない。ホストがこのビューポートのキーボード
+     * スクロールを既に持つ場合 (行のロービングフォーカスと矢印 / Page / Home / End、グリッドのキーボードモデル) に
+     * `false` を指定 — 矢印はその経路の重複となり、キーボード利用者にバー 1 本あたり 2 回の余分な Tab を
+     * 課すため (ネイティブのスクロールバーも Tab の止まり先にならない)。既定を `true` に据え置く理由は、
+     * ホスト側のモデルが無ければ矢印がキーボード利用者の Tab で届く唯一のスクロール操作部品であること
+     * (`ScrollPane` / `VirtualScroll` はコンテンツを transform で動かすため、ブラウザがフォーカス可能に
+     * できるネイティブのスクロール領域が無く、行も Tab の止まり先ではない)。矢印が無効な間
+     * (`enableArrowButtons: false` またはスクロール不要) は効果なし — disabled のボタンはそもそもフォーカス不能。
+     */
+    enableArrowButtonTabStops?: boolean;
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
     horizontal?: boolean;
     /**
@@ -266,6 +300,6 @@ export declare const computeAutoTapScrollMaxSpeedMultiplier: (itemCount?: number
  *
  * カスタムスクロールバーコンポーネント。
  */
-export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, enableHorizontalTapCircle, stretchMainSize, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, locale, labels, }: ScrollBarProps) => import("react").JSX.Element;
+export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, enableArrowButtonTabStops, horizontal, enableHorizontalTapCircle, stretchMainSize, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, locale, labels, }: ScrollBarProps) => import("react").JSX.Element;
 export {};
 //# sourceMappingURL=ScrollBar.d.ts.map

package/dist/ScrollBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollBar.d.ts","sourceRoot":"","sources":["../src/ScrollBar.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollBar.d.ts","sourceRoot":"","sources":["../src/ScrollBar.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrD,OAAO,EAA8B,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGpH,OAAO,EAA8E,KAAK,0BAA0B,EAAE,MAAM,uBAAuB,CAAA;AAgEnJ;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACpC,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,SAAS,CAAA;IAC/D,4FAA4F;IAC5F,aAAa,CAAC,EAAE;QACZ,qEAAqE;QACrE,oBAAoB,EAAE,MAAM,CAAA;QAC5B,gEAAgE;QAChE,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,4EAA4E;QAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;KACvB,CAAA;CACJ,CAAA;AAED,KAAK,8BAA8B,GAAG,QAAQ,CAAC,IAAI,CAAC,yBAAyB,EAAE,WAAW,GAAG,mBAAmB,GAAG,cAAc,GAAG,eAAe,CAAC,CAAC,GAAG;IACpJ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,YAAY,CAAC,EAAE,yBAAyB,CAAC,cAAc,CAAC,CAAA;IACxD,aAAa,CAAC,EAAE,yBAAyB,CAAC,eAAe,CAAC,CAAA;CAC7D,CAAA;AAMD,qIAAqI;AACrI,eAAO,MAAM,uBAAuB,oCAAoC,CAAA;AAExE;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC3C,WAAW,EAAE,UAAU,GAAG,YAAY,CAAA;IACtC,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,MAAM,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;IACnB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;IACpB,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAA;IACtB,wIAAwI;IACxI,QAAQ,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IACrH,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,sBAAsB,CAAC,EAAE,yBAAyB,CAAA;IAClD,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,SAAS,CAAA;IAC3E,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,2BAA2B,CAAA;CACvC,CAAA;AAQD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;IAClC,mDAAmD;;IAEnD,wBAAwB;;CAElB,CAAA;AAYV,eAAO,MAAM,kCAAkC,QAAS,CAAA;AAExD,eAAO,MAAM,iCAAiC,EAAE,8BAY/C,CAAA;AAiCD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAI,SAAS,yBAAyB,GAAG,SAAS,EAAE,YAAY,MAAM,KAAG,8BAiBlH,CAAA;AAmID;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,wBAAwB;IACxB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wBAAwB;IACxB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,2BAA2B,EAAE,OAAO,CAAA;IACpC,kDAAkD;IAClD,KAAK,CAAC,EAAE;QAAE,oBAAoB,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5F,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,eAAO,MAAM,qBAAqB,GAAI,qHAAqH,mBAAmB,KAAG,MAuChL,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC,GAAI,YAAY,MAAM,WASxE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,wVAsBvB,cAAc,gCAu8BhB,CAAA"}