@aiquants/virtualscroll 3.1.1 → 3.5.0

package/CHANGELOG.md

@@ -2,7 +2,165 @@
 
 All notable changes to `@aiquants/virtualscroll` are documented here.
 
-## 3.1.1 (未リリース)
+## 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` は正準空窓
+  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 は
+  そこでも正確)。T = 0 は DOM 構造・インライン属性までバイト恒等 (F = 0 / R = 0 恒等の双子)。
+  `scrollToCell` / `initialScrollAnchor` の末尾狙いは当該軸 no-op (列は既存アンカー残置)、
+  `updateRowSize` / `focusRowAtIndex` は 3 分岐 (末尾帯行は `trailingRowEpoch` 繰上げ / 帯行 DOM
+  直接フォーカス)、`getContentSize().height` = H_F + 埋め込み + H_T。
+- **`getFrozenSize` の 10 フィールド化 (非破壊)**: `{cols, width, rows, height}` に
+  `trailingCols` / `trailingRows` (クランプ後実効カウント)・`trailingWidth` / `trailingHeight`
+  (木 px — 接尾辞和)・`trailingVisibleWidth` / `trailingVisibleHeight` (ビューポートクリップ =
+  `min(木, max(0, viewport − 先頭))` — プレアタッチは 0) を追加。
+- **`--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 へゲート分離**: 従来は凍結分岐と結合して
+  いたため、末尾のみ (F = 0 ∧ T > 0) のグリッドが凍結列ゼロで全行に属性を出す嘘になるところ
+  だった。class `aqvs-grid-row-frozen-host` は「横帯モード」の描画トレイトとして残る。既存構成
+  (F > 0 / T = 0) への挙動変化ゼロ。
+- **ADR-23 — T の実行時変更は埋め込み VirtualScroll を再マウントしない**: `key` は R 専用のまま、
+  itemCount が**末尾**で伸縮するだけ (getItem / getItemKey / getItemHeight = i + R 不変)。視点は
+  トグルを跨いで無償保存される。**保留アンカーの帰結 (文書化)**: T 増加で末尾帯入りする行を
+  狙った保留行アンカーは最終スクロール行へクランプされる (itemCount 変化ごとの再ピン留め +
+  `sanitizeIndex` — 「保留アンカーは R 再マウントで死ぬ」の鏡像)。MV-TR-A1..A4 ゲートで実測確定
+  (740/740 全緑)。
+
+## 3.4.0 (2026-09-03)
+
+- **修正 — コンテンツが viewport に収まる場合の `maxScrollPosition` を 0 へクランプ**:
+  `ScrollBar` のレンダー経路が素の `contentSize - viewportSize` のままで、収まりバンドの
+  `aria-valuemax` に負値 (例 -169) が露出していた (valuemax < valuemin の ARIA 違反 —
+  スプレッドシートの `/format` 実測で検出)。`getScrollBarMetrics` と同一のクランプ規約へ統一。
+  サムはトラック全長 (スクロール余地なしの表明) で従来どおり。クランプ撤去で赤くなる
+  ゲートを `ScrollBar.spec.tsx` に追加 (695/695 全緑)。
+
+- **新機能 — `VirtualGrid` の凍結先頭行 (`frozenLeadingRows`)**: 帯外バンド + インデックス
+  シフト方式 (行凍結設計プラン §2)。凍結行 [0, R) はグリッド所有の `.aqvs-grid-frozen-rows`
+  バンドとして pane の外 (上) に描画し、行本体は `renderRow` をそのまま再利用 — F > 0 の
+  凍結セル構造 (静的セル / row-scroll クリップ / hx 残差 var) が帯行内でも成立し**凍結行 ×
+  凍結列の 4 象限コーナーが無償で成立**。埋め込み VirtualScroll にはシフト済み行空間
+  (`itemCount = rowCount − R`、`getItem = i + R`、`viewportSize = viewport 高 − H_F`) だけを
+  渡すため vy は帯論理・縦バーは帯を自然に写像する。翻訳シームは onRangeChange (+R、全行
+  凍結は正準空窓 start > end) / scrollToCell (凍結行の y は no-op) / initialScrollAnchor /
+  getScrollAnchor / updateRowSize / focusRowAtIndex / onRowFocus (+R ラップ — バンド行も
+  フル行 index で発火) の 7 点。契約: [0,
+  `MAX_FROZEN_LEADING_ROWS` = 128] の整数 fail-fast・rowCount 超過は動的クランプ (全行凍結)・
+  R = 0 は DOM 構造まで従来と恒等 (F = 0 恒等契約の双子)。`getFrozenSize()` は
+  `{cols, width, rows, height}` へ拡張 (非破壊のフィールド追加)。帯に第 2 の格納庫 (木) は
+  無くヒール機構も持たない (アクセサが唯一の真実 — 列凍結帯との宣言済み非対称)。
+- **欠陥是正 — 横バーの帯整列 (利用側実証)**: F > 0 で `.aqvs-grid-hbar-strip` のトラック /
+  サムが凍結帯の下へ食い込み右側 W_F px が空く視覚欠陥を、パッケージ CSS の
+  `padding-left: var(--aqvs-grid-frozen-width, 0px)` で是正 (トラック原点 = スクロール帯
+  開始)。F = 0 は変数不在 → 0px・インライン属性も足さないため DOM / 描画とも従来恒等。
+- **欠陥是正 — ENGINE-R1 敵対レビュー (major 2 + minor 2)**: (1) 縮退帯 (H_F ≥ viewport)
+  の正準空窓化 — 埋め込み itemCount を 0 へ強制 (スクロール行 DOM ゼロ) + 通知を正準空窓
+  (rendering / visible とも start > end・vy 0) へ整形。(2) `frozenLeadingRows` の実行時変更
+  は埋め込み VirtualScroll を key 再マウントで木ごと再構築 (シフト再ペアリングを changeSize
+  末尾意味論に委ねる旧経路は総高 +228px 汚染 — 実測) し、可視先頭アンカーをフル行空間で
+  持ち越して視点保存する (保留 scrollToCell アンカーの ΔR ドリフトも再マウント消滅で同時
+  解消)。(3) バンド行に右インセット (right = 縦バー幅) + overflow クリップ — 縦バー上の
+  コーナー帯を予約。(4) 帯行リサイズは onRangeChange を明示再配送し totalHeight が鮮度で
+  追随 (帯高は格納せず組立て時に毎回加算)。
+- **欠陥是正 — ENGINE-R2 敵対レビュー (major 1 + perf 1 + polish 1)**: (1) **視点テレポート
+  是正 (トグルアンカーの三状態化)** — R 実行時変更アンカーを捕捉値と独立の `toggledRef` で
+  三状態化し、一度でもトグルすればマウント props アンカーを二度と再適用しない。退場側の
+  埋め込み itemCount 0 (全行凍結 / 縮退帯 / rowCount 過渡 0) を経ると消費済みで久しいマウント
+  アンカーが key 再マウントで蘇り視点が y = 1200 へ飛んでいた (2 度再現) — 捕捉 null は
+  undefined (先頭) へ落として根治。(2) **`onItemFocus` memo 安定化** — +R ラップを
+  `[effectiveFrozenRows, hasRowFocus]` 安定の useMemo (`onRowFocus` は ref 経由読み) へ是正。
+  インラインアロー直渡しが横スクロール毎 rAF で React.memo VirtualScrollItem の bail を崩し
+  全行を再レンダーさせていた 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 ⚠️ 等価。
+  `VirtualGridFrozen.spec.tsx` の `getFrozenSize` deep-equal ピン 4 件も rows / height 込みへ
+  更新)。
+
+## 3.3.0 (単独未公開 — 3.4.0 に同梱して公開)
+
+- **新機能 — `VirtualGrid` の凍結先頭列 (`frozenLeadingCols`)**: 設計 §8 の 3 形状要件を実装。
+  (a) スクロール帯の窓探索は木座標 W_F + hx 始まり (幅 0 凍結列の床クランプ込み)、(b) 残差は
+  静的クリップ (`.aqvs-grid-row-scroll`) 内の inner が `calc(残差 − W_F)` で運ぶ (クリップと
+  transform の分離は構造要件)、(c) 凍結帯はアンカー機構の外の静的 subtree (木絶対 left 直接
+  描画 — `data-aqvs-frozen-row` / `data-aqvs-frozen-cell`)。maxHx / アンカー捕獲・解決 /
+  横バー写像 / セル予算 / 打切り分子 / self-heal (帯専用バーストガード) を帯座標系へ一般化し、
+  **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 の正準記録)。
+
+## 3.2.0 (単独未公開 — 3.4.0 に同梱して公開)
+
+- **新機能 — `VirtualGrid`**: 行方向と全く同じロジックで列方向を仮想化する汎用 2D プリミティブ。
+  疎 Fenwick 幅木 (第 2 インスタンス)・共有 `computeRenderingRanges` (BigInt huge 分岐込み)・
+  量子化列アンカー再基準化 (`ANCHOR_REBASE_DISTANCE` 共有)・合成スクロールにより、列数は
+  行と対称の **2^53 − 1** まで、深部でも DOM 座標は完全精度帯 (≤ 2^24 px) に有界。個別トラック
+  は `MAX_TRACK_SIZE` (2^18 px) で fail-fast、セル数は `MAX_RENDERED_CELLS` で非無言打切り
+  (`onRenderTruncated` — 分母の実効描画行数は初回通知前も同期見積りで確定し、マウントコミット
+  から上限内)。高さ 0 (非表示) 行はセル DOM を生成しない (幅 0 列スキップの行双子 — 消費側の
+  セル装飾残留とセル予算浪費の防止)。自己計測はレイアウト px (clientWidth / clientHeight — gBCR は
+  祖先 transform scale のズームホストで視覚 px を返し全幾何が z 倍へ歪む)。幅変更 (`updateColSize` / self-heal) は幅エポックで窓キー不変でも再描画。横残差
+  の消費者はグリッド所有 `.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 認証済み)。
+- **シーム — `ScrollPane` / `VirtualScroll` に `onPanHorizontal`**: ポインタパン横成分の委譲
+  (onWheelHorizontal のパン対・同符号・per-move 増分・押下時横 scale 除算)。指定時は横移動でも
+  ドラッグが発動する。未指定の既存消費者への影響ゼロ。❗ 横軸を `Omit<>` で封じるラッパー
+  (directory-tree) は 3.2.0 更新時に本シームを封印リストへ追加し (pass-through review)、
+  **select-box / daily-report の影響なし確認**も同時に行うこと (設計 §11)。
+- **改修 — `ScrollBar` 横タップサークル**: `enableHorizontalTapCircle` (opt-in — 単体既定不変)
+  で横バーにもタップスクロールサークルを描画。`TapScrollCircle` の方向・距離・デッドゾーン
+  導出を軸パラメータ化 (`axis` prop)。
+- **改修 — 共有機構の追加口**: `FenwickMapTree` / `useFenwickMapTree` に `options.baseValue`
+  (明示 baseValue でサンプリング省略 — 不正値 RangeError、値変化で reset)。`ZERO_HEIGHT_RUN_LIMIT` /
+  `MAX_RENDERED_ITEMS` を module export 化 (バレル非公開 — VirtualGrid 列軸との定数共有)。
+- **堅牢化 (敵対的レビュー R1〜R2 の全指摘反映)**: 動的 `colCount` への総幅恒常同期 (旧上限
+  固着・0 → N の幅 0 固着の根治、同 tick クランプの鮮度込み)。セル上限分母は具現化行ウォーク
+  (非表示 0 高行も計数・共有 `MAX_RENDERED_ITEMS` 上限) + ビューポート高変化時の実測即時無効化 +
+  実測通知の引継ぎで、マウント / リサイズ / 深部移動のどのコミットも有界。振動 `getColWidth`
+  (契約違反) は `WIDTH_HEAL_BURST_LIMIT` で治癒を有界縮退 (警告つき — 無限マイクロタスク旋回の
+  根治)。`initialScrollAnchor` / `scrollToCell` は列アンカーを張り self-heal の実測化へ再ピン留め
+  (手動横入力で解除 — 行側と同契約)。`resetOnGetColWidthChange` / `resetOnGetItemHeightChange` は
+  アクセサ identity を再構築キーへ届くよう修正 (従来は構造的に不発)。`defaultColWidth` は実行時
+  変更にも追随。liveRegion は行側契約へ整列 (既定 400ms・不正値は警告 + 無効化 — 黙示代替も変異で
+  封止)。横タップサークルへ `itemCount = colCount` を自動配線しタップ速度の log10(colCount) 則
+  (設計 B7 対策) を実現、`tapScrollCircleOptions` も横バーへ透過。self-heal バーストは窓非依存の
+  「連続する非収束」計数 (解消は収束パスのみ — 窓端を動かす振幅の振動アクセサにも回避されず、
+  停止後はどの窓かでの収束 1 回で再武装。逐次の正当な治癒は誤認しない)。
+- **品質**: vitest 648 / 648 = 単体 618 + 統合 30 (VirtualGrid 59 + 横シーム 10 + Fenwick baseValue 4
+  の新設ゲート込み)・変異 56 本 (MV-A〜MV-BD — アンカー / 残差 / 上限 / 打切り / 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。
+
+## 3.1.1 (2026-08-28)
 
 ### Fixed
 

package/README.md

@@ -300,9 +300,9 @@ focus, so if you want keyboard-only users to reach it, give them an entry point
 `handle.focusItemAtIndex(0)` when the list receives focus.
 
 ⚠️ **Wrappers that own the horizontal axis should seal these too.** If you re-export VirtualScroll with
-`Omit<VirtualScrollProps, 'onWheelHorizontal'>`, add `horizontalKeyInputs` and `horizontalKeyStep` to
-that same `Omit`. They sit at the top level, next to `onWheelHorizontal`, precisely so one `Omit` closes
-the whole horizontal seam.
+`Omit<VirtualScrollProps, 'onWheelHorizontal'>`, add `onPanHorizontal` (3.2.0), `horizontalKeyInputs`
+and `horizontalKeyStep` to that same `Omit`. All four sit at the top level, next to each other,
+precisely so one `Omit` closes the whole horizontal seam.
 
 ## Escape row-return
 
@@ -345,6 +345,99 @@ non-finite) logs a warning and disables announcements instead of silently substi
 default. ⚠️ If your app already maintains its own live region for the list, keep using
 `onRangeChange` instead — two regions double-announce.
 
+## VirtualGrid (2D — trillion-scale columns, v3.2.0)
+
+`VirtualGrid` composes the proven row axis (an embedded `VirtualScroll`) with a symmetric
+horizontal column engine built from the SAME machinery: a second sparse Fenwick width tree,
+the shared rendering-range computation (BigInt huge branch included), quantized column-anchor
+rebasing at the shared `ANCHOR_REBASE_DISTANCE`, and synthetic scrolling — total-size pixels
+never land in the DOM, so `colCount` inherits the full row-axis profile (`<= 2^53 - 1`; ten
+trillion columns sit comfortably inside).
+
+```tsx
+<VirtualGrid<string>
+    rowCount={1_000_000_000_000}
+    colCount={1_000_000_000_000}
+    getRowHeight={() => 24}
+    getColWidth={() => 100}
+    getCell={(row, col) => `${row}:${col}`}
+    contentProps={{ role: "grid" }}          // composite role belongs to the consumer
+    getCellProps={(row, col) => ({ role: "gridcell" })}
+    onRenderTruncated={(info) => console.warn(info)} // the cell cap is never silent
+>
+    {(cell) => <span>{cell}</span>}
+</VirtualGrid>
+```
+
+Contracts (see the design plan under `docs/plans/` for the full bounding theorem):
+
+- `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).
+- Per-axis overscan defaults to 3 (a deliberate, documented deviation from the bare
+  `VirtualScroll` default of 15 — the bounding contract's window-span term is
+  overscan-proportional). With the defaults, ancestor `scale(z)` stays in the full-precision
+  band up to z ≈ 5.3.
+- The handle mirrors the row contracts: logical coordinates, `-1` sentinels pre-attach,
+  `scrollBy`/`scrollTo` return the applied clamped position synchronously, `applyWheel`
+  returns a boolean for `useWheelBridge`, and `{index, offset}` anchors
+  (`getScrollAnchor` / `initialScrollAnchor`) replace raw-px restore.
+- Header sync: derive the window origin (`offsetOf(renderingColStart)`) from YOUR geometry
+  source, position header cells window-relative, and translate the header track by
+  `origin - scrollX` per `onScroll` — the same scheme the row-side headers use. LTR only (v1).
+- 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`.
+- 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
+  `[0, MAX_FROZEN_LEADING_COLS]` (128) — `RangeError` otherwise; values beyond the current
+  `colCount` freeze every column (documented dynamic clamp). `scrollToCell` /
+  `initialScrollAnchor` targeting a frozen column are horizontal no-ops (always visible), and
+  `getFrozenSize()` reports the effective `{cols, width, rows, height, trailingCols,
+  trailingRows, trailingWidth, trailingHeight, trailingVisibleWidth, trailingVisibleHeight}`
+  (both axes, both ends — the `rows`/`height` fields are a non-breaking v3.4.0 addition and
+  the six `trailing*` fields a non-breaking v3.5.0 addition; `trailingWidth`/`trailingHeight`
+  are TREE px, the `trailingVisible*` pair is the viewport clip `min(tree, max(0, viewport -
+  leading))`) for consumer hit-test partitioning.
+  Frozen cells precede the scroll band in row DOM (logical column order for AT / tabbing), and
+  an all-frozen grid reports the scroll band as the canonical EMPTY window (`renderingColStart
+  > renderingColEnd` — inclusive loops run zero iterations). `frozenLeadingCols` of `0` (the
+  default) is structurally identical to the pre-frozen DOM.
+- Frozen leading rows (v3.4.0): `frozenLeadingRows` pins the first R rows as a grid-owned band
+  ABOVE the scroll pane (out-of-pane band + index shift: the embedded row axis only ever sees
+  the shifted space `rowCount - R`, so the vertical bar maps the scroll band naturally — no
+  bar inset needed). Band rows reuse the normal row renderer, so frozen columns keep working
+  inside them (the frozen-rows x frozen-cols 4-quadrant corner comes for free). Integer in
+  `[0, MAX_FROZEN_LEADING_ROWS]` (128) — `RangeError` otherwise; values beyond the current
+  `rowCount` freeze every row (documented dynamic clamp — the scroll rows then report the
+  canonical EMPTY window `renderingRowStart > renderingRowEnd`), as does a degenerate band
+  (H_F fills the measured viewport — zero scroll-row DOM). `scrollToCell` /
+  `initialScrollAnchor` targeting a frozen row are vertical no-ops (always visible),
+  `contentInsets.top` remains leading blank space INSIDE the scroll band (a pinned band is not
+  an inset), and `frozenLeadingRows` of `0` (the default) is structurally identical to the
+  pre-frozen DOM. Changing `frozenLeadingRows` at runtime rebuilds the embedded row tree
+  (remount) and preserves the visible-top viewpoint across the toggle.
+- Frozen trailing columns / rows (v3.5.0): `frozenTrailingCols` pins the last T columns in a
+  right-anchored clip outside the anchor machinery (band-local lefts; the scroll band
+  generalizes to `viewport - W_F - W_T` with a right clip inset driven by
+  `--aqvs-grid-trailing-width` — written only while T > 0, `0px` fallback otherwise), and
+  `frozenTrailingRows` pins the last T rows as a second grid-owned band BELOW the scroll pane
+  (clip height = the visible size `min(H_T, max(0, viewport - H_F))`, inner bottom-anchored at
+  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
+  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
+  place). Changing `frozenTrailingCols`/`frozenTrailingRows` at runtime does NOT remount the
+  embedded row axis (the tail-only itemCount change keeps the viewpoint for free; a pending
+  row anchor whose target enters the band clamps to the last scroll row), and a value of `0`
+  (the default) is structurally identical to the pre-trailing DOM.
+
 ## Residual quantizer for snapping consumers
 
 Consumers that snap positions to a fixed quantum (row height, column width) lose sub-quantum
@@ -437,6 +530,7 @@ exists in the DOM.
 | `onScroll` | `(position: number, totalHeight: number) => void` | ❌ | Scroll event handler |
 | `onRangeChange` | `(range: VirtualScrollRange) => void` | ❌ | Range change handler |
 | `onWheelHorizontal` | `(deltaX: number) => void` | ❌ | Opt-in horizontal delegation. Horizontal-dominant wheel / trackpad gestures (and shift+wheel) are delegated to this handler so the parent can implement horizontal scrolling. ⚠️ **Keyboard deltas arrive here too** when `horizontalKeyInputs` is set. When omitted, horizontal gestures bypass vertical scrolling so parent native scrolling works. See [Horizontal Scrolling](#horizontal-scrolling). |
+| `onPanHorizontal` | `(deltaX: number) => void` | ❌ | Opt-in delegation of the horizontal component of pointer pans (touch / pen drags) — the pan twin of `onWheelHorizontal` with the same sign convention, per-move increments divided by the press-time x-axis ancestor scale (3.2.0). When set, purely horizontal pans also activate the drag. Same seal family as `onWheelHorizontal` — wrappers sealing the horizontal axis must `Omit` this name too. |
 | `horizontalKeyInputs` | `readonly "arrow"[]` | ❌ | Keyboard gestures that emit a horizontal delta through `onWheelHorizontal` (default: `[]`, so row-level arrow handling is never stolen). `Shift + ←/→` is never consumed. Fires only when the row itself is the event target. ⚠️ Requires `behaviorOptions.enableKeyboardNavigation` (default `true`) — with it off the rows have no key handler at all and this prop does nothing (the package warns) |
 | `horizontalKeyStep` | `number` | ❌ | Pixels per horizontal arrow press (default: 40). Must be finite and positive; anything else warns and leaves the key untouched |
 | `background` | `ReactNode` | ❌ | Background element |

package/dist/ScrollBar.d.cts

@@ -75,6 +75,14 @@ export type ScrollBarProps = {
     enableArrowButtons?: boolean;
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
     horizontal?: boolean;
+    /**
+     * Opt-in: renders the tap-scroll circle on HORIZONTAL bars too (default false — the bare
+     * horizontal bar's shipped behavior is unchanged; VirtualGrid enables this for trillion-column
+     * reachability, v3.2.0). Vertical bars are unaffected by this flag.
+     * 横バーにもタップスクロールサークルを描画する opt-in (既定 false — 単体横バーの既定挙動は
+     * 不変。VirtualGrid が兆列到達性のために有効化する、v3.2.0)。縦バーには影響しない。
+     */
+    enableHorizontalTapCircle?: boolean;
     /** The width of the scrollbar. / スクロールバーの幅。 */
     scrollBarWidth?: number;
     /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
@@ -220,4 +228,4 @@ export declare const computeAutoTapScrollMaxSpeedMultiplier: (itemCount?: number
  *
  * カスタムスクロールバーコンポーネント。
  */
-export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, }: ScrollBarProps) => import("react").JSX.Element;
+export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, enableHorizontalTapCircle, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, }: ScrollBarProps) => import("react").JSX.Element;

package/dist/ScrollBar.d.ts

@@ -75,6 +75,14 @@ export type ScrollBarProps = {
     enableArrowButtons?: boolean;
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
     horizontal?: boolean;
+    /**
+     * Opt-in: renders the tap-scroll circle on HORIZONTAL bars too (default false — the bare
+     * horizontal bar's shipped behavior is unchanged; VirtualGrid enables this for trillion-column
+     * reachability, v3.2.0). Vertical bars are unaffected by this flag.
+     * 横バーにもタップスクロールサークルを描画する opt-in (既定 false — 単体横バーの既定挙動は
+     * 不変。VirtualGrid が兆列到達性のために有効化する、v3.2.0)。縦バーには影響しない。
+     */
+    enableHorizontalTapCircle?: boolean;
     /** The width of the scrollbar. / スクロールバーの幅。 */
     scrollBarWidth?: number;
     /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
@@ -220,5 +228,5 @@ export declare const computeAutoTapScrollMaxSpeedMultiplier: (itemCount?: number
  *
  * カスタムスクロールバーコンポーネント。
  */
-export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, }: ScrollBarProps) => import("react").JSX.Element;
+export declare const ScrollBar: ({ contentSize, viewportSize, scrollPosition, onScroll, enableThumbDrag, enableTrackClick, enableArrowButtons, horizontal, enableHorizontalTapCircle, scrollBarWidth, className, ariaControls, tapScrollCircleOptions, itemCount, renderThumbOverlay, visibleStartIndex, visibleEndIndex, }: ScrollBarProps) => import("react").JSX.Element;
 //# 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":"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"}

package/dist/ScrollPane.d.cts

@@ -115,6 +115,19 @@ export type ScrollPaneProps = {
      * 指定時は横スクロールを委譲処理し、未指定時でも Shift+ホイール 等の横ジェスチャは縦スクロールで横取りせず親要素のスクロールへ委ねる。
      */
     onWheelHorizontal?: (deltaX: number) => void;
+    /**
+     * Delegates the horizontal component of a pointer pan (touch / pen drag) upstream, in the
+     * SAME sign convention as onWheelHorizontal (positive = scroll right). Emitted as per-move
+     * increments, divided by the press-time ancestor scale (x axis). When set, drag activation
+     * also considers horizontal finger travel so a purely horizontal pan can start a drag.
+     * Vertical pan / inertia behavior is unchanged (the pane stays a 1-axis owner — this is a
+     * delegation seam, mirroring onWheelHorizontal; v3.2.0 VirtualGrid seam).
+     * ポインタパン (タッチ / ペン) の横成分を上流へ委譲する (符号は onWheelHorizontal と同一 —
+     * 正 = 右へスクロール)。per-move 増分で配送し、押下時採取の横軸祖先 scale で除算する。
+     * 指定時はドラッグ発動判定に横移動量も含める (純横パンでもドラッグが始まる)。縦のパン /
+     * 慣性は不変 — ペインは 1 軸所有者のままの委譲シーム (onWheelHorizontal の対、v3.2.0)。
+     */
+    onPanHorizontal?: (deltaX: number) => void;
     /** Insets applied to the scrollable content area. / スクロール可能領域に適用するインセット。 */
     contentInsets?: ScrollPaneContentInsets;
     /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */

package/dist/ScrollPane.d.ts

@@ -115,6 +115,19 @@ export type ScrollPaneProps = {
      * 指定時は横スクロールを委譲処理し、未指定時でも Shift+ホイール 等の横ジェスチャは縦スクロールで横取りせず親要素のスクロールへ委ねる。
      */
     onWheelHorizontal?: (deltaX: number) => void;
+    /**
+     * Delegates the horizontal component of a pointer pan (touch / pen drag) upstream, in the
+     * SAME sign convention as onWheelHorizontal (positive = scroll right). Emitted as per-move
+     * increments, divided by the press-time ancestor scale (x axis). When set, drag activation
+     * also considers horizontal finger travel so a purely horizontal pan can start a drag.
+     * Vertical pan / inertia behavior is unchanged (the pane stays a 1-axis owner — this is a
+     * delegation seam, mirroring onWheelHorizontal; v3.2.0 VirtualGrid seam).
+     * ポインタパン (タッチ / ペン) の横成分を上流へ委譲する (符号は onWheelHorizontal と同一 —
+     * 正 = 右へスクロール)。per-move 増分で配送し、押下時採取の横軸祖先 scale で除算する。
+     * 指定時はドラッグ発動判定に横移動量も含める (純横パンでもドラッグが始まる)。縦のパン /
+     * 慣性は不変 — ペインは 1 軸所有者のままの委譲シーム (onWheelHorizontal の対、v3.2.0)。
+     */
+    onPanHorizontal?: (deltaX: number) => void;
     /** Insets applied to the scrollable content area. / スクロール可能領域に適用するインセット。 */
     contentInsets?: ScrollPaneContentInsets;
     /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */

package/dist/ScrollPane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollPane.d.ts","sourceRoot":"","sources":["../src/ScrollPane.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollPane.d.ts","sourceRoot":"","sources":["../src/ScrollPane.tsx"],"names":[],"mappings":"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"}

package/dist/TapScrollCircle.d.cts

@@ -14,6 +14,12 @@ export type TapScrollCircleDragState = {
     pointerId: number | null;
 };
 export type TapScrollCircleProps = {
+    /**
+     * Axis the direction/distance/dead-zone derivation reads (default "y" — vertical bars).
+     * Horizontal bars pass "x" so a horizontal circle drag scrolls horizontally (v3.2.0).
+     * 方向・距離・デッドゾーン導出が読む軸 (既定 "y" — 縦バー)。横バーは "x" を渡す (v3.2.0)。
+     */
+    axis?: "x" | "y";
     /** Called whenever the drag state updates. / ドラッグ状態が更新された際に呼び出されるコールバック。 */
     onDragChange: (state: TapScrollCircleDragState) => void;
     /** Additional class names for styling. / 追加のスタイル用クラス名。 */
@@ -25,7 +31,7 @@ export type TapScrollCircleProps = {
     /** Additional inline styles. / 追加のインラインスタイル。 */
     style?: CSSProperties;
     /** Base opacity applied to the circle. / サークル全体に適用する基準透明度。 */
-    opacity: number;
+    opacity?: number;
     /** Custom rendering logic for the visual contents. / ビジュアル内容を描画するカスタムロジック。 */
     renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode;
 };

package/dist/TapScrollCircle.d.ts

@@ -14,6 +14,12 @@ export type TapScrollCircleDragState = {
     pointerId: number | null;
 };
 export type TapScrollCircleProps = {
+    /**
+     * Axis the direction/distance/dead-zone derivation reads (default "y" — vertical bars).
+     * Horizontal bars pass "x" so a horizontal circle drag scrolls horizontally (v3.2.0).
+     * 方向・距離・デッドゾーン導出が読む軸 (既定 "y" — 縦バー)。横バーは "x" を渡す (v3.2.0)。
+     */
+    axis?: "x" | "y";
     /** Called whenever the drag state updates. / ドラッグ状態が更新された際に呼び出されるコールバック。 */
     onDragChange: (state: TapScrollCircleDragState) => void;
     /** Additional class names for styling. / 追加のスタイル用クラス名。 */
@@ -25,7 +31,7 @@ export type TapScrollCircleProps = {
     /** Additional inline styles. / 追加のインラインスタイル。 */
     style?: CSSProperties;
     /** Base opacity applied to the circle. / サークル全体に適用する基準透明度。 */
-    opacity: number;
+    opacity?: number;
     /** Custom rendering logic for the visual contents. / ビジュアル内容を描画するカスタムロジック。 */
     renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode;
 };

package/dist/TapScrollCircle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TapScrollCircle.d.ts","sourceRoot":"","sources":["../src/TapScrollCircle.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAqC,MAAM,OAAO,CAAA;AAIxF,MAAM,MAAM,wBAAwB,GAAG;IACnC,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAA;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IAC/B,4EAA4E;IAC5E,YAAY,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,SAAS,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;CAC1C,CAAA;AAcD,MAAM,MAAM,0BAA0B,GAAG;IACrC,yDAAyD;IACzD,SAAS,EAAE,wBAAwB,CAAA;IACnC,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,mHA+P3B,CAAA"}
+{"version":3,"file":"TapScrollCircle.d.ts","sourceRoot":"","sources":["../src/TapScrollCircle.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAqC,MAAM,OAAO,CAAA;AAIxF,MAAM,MAAM,wBAAwB,GAAG;IACnC,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAA;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;IAChB,4EAA4E;IAC5E,YAAY,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,SAAS,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;;OAIG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;CAC1C,CAAA;AAcD,MAAM,MAAM,0BAA0B,GAAG;IACrC,yDAAyD;IACzD,SAAS,EAAE,wBAAwB,CAAA;IACnC,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,mHAkQ3B,CAAA"}