@aiquants/virtualscroll 3.1.1 → 3.5.0

package/src/VirtualGrid.tsx

@@ -0,0 +1,1822 @@
+/**
+ * @fileoverview VirtualGrid — a generic 2D virtualization primitive composing the proven
+ * VirtualScroll row axis with a symmetric horizontal column engine (the SAME trillion-scale
+ * machinery: the sparse Fenwick width tree, the shared computeRenderingRanges (incl. its
+ * BigInt huge branch), quantized anchor rebasing at ANCHOR_REBASE_DISTANCE, and synthetic
+ * 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).
+ *
+ * VirtualGrid — 実証済みの VirtualScroll 行軸に、対称の横列エンジン (同一の兆スケール機構:
+ * 疎 Fenwick 幅木・共有 computeRenderingRanges (BigInt huge 分岐込み)・ANCHOR_REBASE_DISTANCE
+ * の量子化アンカー再基準化・総サイズ px を DOM に着地させない合成スクロール) を合成した
+ * 汎用 2D 仮想化プリミティブ。列数は行軸のスケールプロファイル (≤ 2^53 − 1) を完全継承する。
+ * グリッド操作の意味論 (選択 / 編集 / クリップボード) は意図的に非所有 — 消費側が
+ * getCellProps / getRowProps / contentProps で装着する。
+ */
+
+import { type CSSProperties, forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+import { Logger } from "./logger.ts"
+import { ScrollBar } from "./ScrollBar.tsx"
+import type { ScrollPaneProps } from "./ScrollPane.tsx"
+import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { minmax } from "./utils.ts"
+import { ANCHOR_REBASE_DISTANCE, computeRenderingRanges, MAX_RENDERED_ITEMS, VirtualScroll, type VirtualScrollBehaviorOptions, type VirtualScrollHandle, type VirtualScrollRange, type VirtualScrollScrollBarOptions, ZERO_HEIGHT_RUN_LIMIT } from "./VirtualScroll.tsx"
+
+/**
+ * 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).
+ *
+ * 両軸共通のトラックサイズ上限 (px)。超過は RangeError で fail-fast (暗黙 clamp なし):
+ * §6 の有界化契約はトラック有界性に立脚し、1 本の過大トラックでセル座標 / 残差 transform が
+ * 実測の LayoutUnit 壁 (2^25) を踏み抜くため。
+ */
+export const MAX_TRACK_SIZE = 262_144 // 2^18 px
+
+/**
+ * Per-axis overscan default. Deliberately 3 (NOT the bare VirtualScroll default of 15): the
+ * bounding contract's window-span term is overscan-proportional, and 2D multiplies overscan
+ * cost by the other axis. VirtualGrid injects this into the embedded VirtualScroll explicitly.
+ *
+ * 軸別 overscan 既定。意図的に 3 (素の VirtualScroll 既定 15 ではない): 有界化契約の窓スパン
+ * 項が overscan 比例で、2D では他軸との積で費用が増幅されるため。内包 VirtualScroll へも
+ * 明示注入する。
+ */
+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).
+ *
+ * 1 レンダーで具現化するセルノード数 (描画行 × 描画列) の安全上限。行側 MAX_RENDERED_ITEMS
+ * (病的入力ガード) と違い、2D 積は正当な構成 (大型ディスプレイの最小ズーム) で到達し得るため
+ * 打切りは無言にしない — onRenderTruncated が発火する。初期値は WQHD 前提で、最終確定は
+ * 設計計画 §9-3 の所有 (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
+ * 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)。凍結帯は窓化されず全描画行で具現化し、かつ
+ * MAX_RENDERED_CELLS の打切り対象外 (代わりにスクロール帯予算を凍結数ぶん控除) のため、帯を
+ * 有界にするのはこの上限そのもの: 最悪 128 × MAX_RENDERED_ITEMS 行、W_F ≤ 128 × MAX_TRACK_SIZE
+ * = 2^25 (実測壁ちょうど — 実運用は W_F ≤ viewport ≪ 2^24)。違反は fail-fast の RangeError。
+ */
+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
+ * (the budget denominator counts band rows instead), so the cap bounds the band itself.
+ * `frozenLeadingRows` の上限 (行凍結設計 §4-1)。凍結行帯はグリッド所有で埋め込み
+ * VirtualScroll の外 (インデックスシフト方式 — 設計 §2)。帯行は描画列を全て具現化し
+ * 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.
+ *
+ * `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。
+ */
+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.
+ *
+ * `frozenTrailingRows` の上限 (3.5.0 末尾凍結プラン §3)。末尾行帯はグリッド所有で埋め込み
+ * VirtualScroll の外 (ペインの**下**の第 2 帯外バンド)。帯行は描画列を全て具現化し
+ * MAX_RENDERED_CELLS の打切り対象外 (予算分母に帯行数を算入) のため、帯を有界にするのは
+ * この上限そのもの。違反は fail-fast の RangeError。
+ */
+export const MAX_FROZEN_TRAILING_ROWS = 128
+
+/**
+ * Maximum number of CONSECUTIVE NON-CONVERGENT self-heal flushes. A stable accessor converges in
+ * ONE flush (tree == accessor afterwards), so the next collect pass is clean and RESETS this
+ * counter — sequential legitimate width changes never accumulate. A truly oscillating getColWidth
+ * (a contract violation) never produces a clean pass, so the heal→epoch→re-collect microtask
+ * cycle would spin forever — past this limit healing is suspended with a single warning (bounded
+ * degradation instead of a livelock). ❗ The state is deliberately window-agnostic ({count,
+ * warned} — no window key): a key-scoped reset would be evaded forever by an oscillation whose
+ * amplitude moves the window edge (alternating keys every heal — empirically refuted). Recovery
+ * after suspension rides the clean-pass reset: any converged pass in ANY window (e.g. after
+ * scrolling to a healthy region) re-arms healing.
+ *
+ * 「**連続する非収束**」self-heal フラッシュ数の上限。安定したアクセサは 1 回で収束する
+ * (治癒後は 木 == アクセサ) ため次の走査は乖離ゼロとなり本カウンタは**解消**される — 逐次の
+ * 正当な幅変更は蓄積しない。真に振動する getColWidth (契約違反) は収束パスを一度も作れず、
+ * 治癒→エポック→再走査のマイクロタスク循環が無限旋回するため、超過時は治癒を停止し 1 回だけ
+ * 警告する (livelock でなく有界な縮退)。❗ 状態は意図的に窓非依存 ({count, warned} — 窓キーを
+ * 持たない): キー基準の解消は、振幅が窓端を動かす振動が治癒のたびにキーを交互させて永久回避する
+ * (実測反証済み)。停止後の回復は収束パス解消が担う (**どの窓でも**収束 1 回で治癒が再武装する)。
+ */
+const WIDTH_HEAL_BURST_LIMIT = 10
+
+/**
+ * Resolves the per-row column cap from the cell budget and the effective rendered-row count.
+ * Pure and exported as the mutation-gate surface for the production MAX_RENDERED_CELLS fallback
+ * (the component itself is only ever gated through the __maxRenderedCells test seam).
+ *
+ * セル予算と実効描画行数から行あたり列上限を解決する。純関数 — 本番既定 MAX_RENDERED_CELLS への
+ * フォールバックを変異ゲート化するための export (コンポーネント側はテストシーム経由でしか
+ * ゲートできないため)。
+ */
+export const resolveMaxColsPerRow = (maxRenderedCells: number | undefined, renderedRowCount: number): number => Math.max(1, Math.floor((maxRenderedCells ?? MAX_RENDERED_CELLS) / Math.max(1, renderedRowCount)))
+
+/**
+ * Estimates the MATERIALIZED-row count of a commit that precedes the embedded VirtualScroll's
+ * range notification (the notification is a state update and lags one commit — mount and
+ * viewport resizes): walks row indices from `startRow` accumulating real heights until the
+ * viewport is filled, counting EVERY index — zero-height (hidden) rows materialize as DOM rows
+ * too, so counting only visible rows would under-divide the cell budget by the whole hidden run.
+ * The walk is capped by the shared MAX_RENDERED_ITEMS (the row axis truncates its own render at
+ * the same constant), then the rendering-window slack (2 x overscan + 2 boundary rows) is added.
+ *
+ * 内包 VirtualScroll の範囲通知 (state 更新のため 1 コミット遅れる — マウントとビューポート
+ * リサイズ) より前のコミットに対する**具現化行数**の見積り: `startRow` から実行高を積んで
+ * ビューポートを満たすまで**全 index** を数える — 高さ 0 (非表示) 行も DOM 行として具現化される
+ * ため、可視行だけを数えると隠しラン全量ぶんセル予算を過小分割する。ウォークは共有
+ * MAX_RENDERED_ITEMS (行軸自身の描画打切り定数) で上限化し、描画窓スラック (2 x overscan + 2)
+ * を足す。
+ */
+export const estimateRenderedRowCount = (viewportHeight: number, getRowHeight: (row: number) => number, rowCount: number, startRow: number, overscanRows: number): number => {
+    let accumulated = 0
+    let rows = 0
+    let row = Math.max(0, Math.min(startRow, rowCount - 1))
+    // 具現化行の母集団 = 描画窓の index 幅。行軸は窓を MAX_RENDERED_ITEMS で打ち切るため、
+    // ウォークも同じ上限で有界 (高さ 0 の巨大ランでも最大 2,000 歩)
+    while (row < rowCount && accumulated < viewportHeight && rows < MAX_RENDERED_ITEMS) {
+        accumulated += getRowHeight(row)
+        rows += 1
+        row += 1
+    }
+    return Math.max(1, rows + 2 * overscanRows + 2)
+}
+
+/**
+ * 2D range notification payload (rendering = overscan-inclusive, visible = strict; row-parity
+ * with VirtualScrollRange). The all-frozen scroll band reports the CANONICAL EMPTY window as
+ * start > end (renderingColStart = colCount, renderingColEnd = colCount - 1) — inclusive
+ * [start..end] loops naturally run zero iterations; formatters must handle start > end.
+ * 2D 範囲通知 (rendering = オーバースキャン込み、visible = 厳密 — 行側 VirtualScrollRange と
+ * 対称)。全列凍結のスクロール帯は**空窓の正準表現 start > end** (renderingColStart = colCount /
+ * renderingColEnd = colCount − 1) で通知する — 閉区間 [start..end] の列挙は自然に 0 周、
+ * 文言整形側は start > end を扱うこと。
+ */
+export type VirtualGridRange = {
+    renderingRowStart: number
+    renderingRowEnd: number
+    visibleRowStart: number
+    visibleRowEnd: number
+    renderingColStart: number
+    renderingColEnd: number
+    visibleColStart: number
+    visibleColEnd: number
+    /** Logical scroll position (px). / 論理スクロール位置 (px)。 */
+    scrollX: number
+    scrollY: number
+    totalWidth: number
+    totalHeight: number
+}
+
+/** Live-region options: the consumer owns wording/locale (no built-in strings — row-parity). / liveRegion オプション: 文言とロケールは消費側所有 (内蔵文字列なし — 行側と同一方針)。 */
+export type VirtualGridLiveRegionOptions = {
+    /** Builds the announcement (same string = no re-announce, "" clears). / 読み上げ文言の組み立て (同一文字列 = 再読み上げなし、"" でクリア)。 */
+    buildMessage: (range: VirtualGridRange) => string
+    /** Settle debounce before announcing (ms, default 400 — the row-side default). Must be finite and >= 0; anything else logs a warning and disables announcements (no silent substitution — row-parity contract). / 読み上げ前の静定待ち (ms、既定 400 — 行側と同一)。有限かつ 0 以上のみ — それ以外は警告して読み上げを無効化 (黙って既定へ読み替えない — 行側と同契約)。 */
+    debounceMs?: number
+}
+
+/** Behavior options (embeds the vertical VirtualScrollBehaviorOptions + column-axis twins). / 挙動オプション (縦の VirtualScrollBehaviorOptions を包含 + 列軸双子)。 */
+export type VirtualGridBehaviorOptions = VirtualScrollBehaviorOptions & {
+    /**
+     * Rebuilds the column width tree when getColWidth identity changes (the column twin of the
+     * row-side resetOnGetItemHeightChange — for mid-list column insert/delete where index↔width
+     * pairing shifts). Default false.
+     * getColWidth の identity 変化で列幅木を再構築する (行側 resetOnGetItemHeightChange の列
+     * 双子 — 中間挿入 / 削除で index↔幅 対応がずれる場合)。既定 false。
+     */
+    resetOnGetColWidthChange?: boolean
+    /**
+     * Explicit Fenwick baseValue for the column width tree (design §3.4): 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 ストライド
+     * サンプリングを省略し、未具現化列をこの幅で見積もる。[0, MAX_TRACK_SIZE] の整数 —
+     * 違反は RangeError (fail-fast、clamp なし)。
+     */
+    defaultColWidth?: number
+}
+
+/** Props for VirtualGrid. / VirtualGrid の props。 */
+export type VirtualGridProps<T> = {
+    /** Row count (<= 2^53 - 1). / 行数 (≤ 2^53 − 1)。 */
+    rowCount: number
+    /** Column count (<= 2^53 - 1 — full row-axis parity). / 列数 (≤ 2^53 − 1 — 行軸と完全対称)。 */
+    colCount: number
+    /**
+     * Row height accessor — integer px, 0 = hidden, <= MAX_TRACK_SIZE (RangeError otherwise).
+     * Must stay index-stable while the ordering is unchanged (row-side getItemHeight contract).
+     * 行高アクセサ — 整数 px、0 = 非表示、≤ MAX_TRACK_SIZE (超過は RangeError)。並び順が
+     * 不変の間は index 安定であること (行側 getItemHeight と同文の契約)。
+     */
+    getRowHeight: (row: number) => number
+    /** Column width accessor — the width SSOT (same contract as getRowHeight; no eager bulk init is ever performed). / 列幅アクセサ — 幅の SSOT (getRowHeight と同契約。eager な一括初期化は行わない)。 */
+    getColWidth: (col: number) => number
+    /** Cell value accessor (pull型 — the grid holds no data). / セル値アクセサ (pull 型 — グリッドはデータを持たない)。 */
+    getCell: (row: number, col: number) => T
+    /** Stable cell key (default: the column index within the row). / 安定セルキー (既定: 行内の列 index)。 */
+    getCellKey?: (row: number, col: number) => string | number
+    /** Cell renderer. / セルレンダラー。 */
+    children: (cell: T, row: number, col: number) => ReactNode
+    /** Attributes merged onto the positioned cell element (roles / aria-* / data-* — the consumer hook surface). / 配置済みセル要素へマージする属性 (role / aria / data — 消費側フック面)。 */
+    getCellProps?: (row: number, col: number) => HTMLAttributes<HTMLDivElement>
+    /** Attributes merged onto the row wrapper (role="row" / aria-rowindex). / 行ラッパーへマージする属性。 */
+    getRowProps?: (row: number) => HTMLAttributes<HTMLDivElement>
+    /**
+     * ARIA / identity attributes for the scrollable content element (role="grid" etc.) — the
+     * EXACT row-side type (ScrollPaneProps["contentProps"]): deliberately NOT HTMLAttributes, so a
+     * consumer cannot smuggle className / style past the pane's structural class and inline
+     * geometry (the pane spreads contentProps after its own className — a wide type here would be
+     * a type-system bypass that clobbers overflow / position / flex in real browsers).
+     * スクロール面要素への ARIA / 識別属性 (role="grid" 等) — 行側と完全同型
+     * (ScrollPaneProps["contentProps"])。意図的に HTMLAttributes ではない: 広い型にすると
+     * className / style がペインの構造クラスとインライン形状を後勝ちで破壊できてしまう
+     * (型システムバイパス — 実ブラウザで overflow / position / flex が消える)。
+     */
+    contentProps?: ScrollPaneProps["contentProps"]
+    /** Background layer rendered inside the content element behind the rows (row-side pass-through). / 行の背後・コンテンツ要素内に描画する背景レイヤー (行側の透過)。 */
+    background?: ReactNode
+    /** Vertical content insets (px) around the rows (row-side pass-through — the horizontal axis has no inset concept in v1). / 行の上下コンテンツインセット (px、行側の透過 — 横軸のインセットは v1 非対応)。 */
+    contentInsets?: ScrollPaneProps["contentInsets"]
+    /** Fires when a row wrapper receives focus, in FULL row space (scroll rows via the +R-wrapped row-side onItemFocus — enableKeyboardNavigation applies; frozen band rows fire on direct DOM focus regardless). / 行ラッパーのフォーカス通知 (フル行空間)。スクロール行は +R ラップ済み行側 onItemFocus (enableKeyboardNavigation が前提)、凍結帯行は直接 DOM フォーカスで無条件発火。 */
+    onRowFocus?: (row: number) => void
+    /**
+     * Keyboard gestures that horizontally scroll the grid-owned axis (default: none — the exact
+     * row-side prop; the emitted delta is consumed internally into hx). Requires
+     * behaviorOptions.enableKeyboardNavigation and focus on a row wrapper (row-side contract).
+     * グリッド所有の横軸をキーボードで動かす操作種別 (既定: 無効 — 行側と同一 prop。放出量は
+     * 内部で hx に消費)。behaviorOptions.enableKeyboardNavigation と行ラッパーへの
+     * フォーカスが前提 (行側と同契約)。
+     */
+    horizontalKeyInputs?: readonly "arrow"[]
+    /** Pixels per horizontal arrow key press (default 40 — row-side pass-through incl. the reject-invalid contract). / 横矢印キー 1 回の移動量 (既定 40 — 不正値拒否契約ごと行側の透過)。 */
+    horizontalKeyStep?: number
+    /** Fires on logical scroll (either axis). / 論理スクロール通知 (どちらの軸でも)。 */
+    onScroll?: (pos: { x: number; y: number }) => void
+    /** Fires when the 2D rendering/visible ranges change. / 2D 範囲変化の通知。 */
+    onRangeChange?: (range: VirtualGridRange) => void
+    /** Fires when the MAX_RENDERED_CELLS cap truncates columns (never silent). / MAX_RENDERED_CELLS 打切りの通知 (無言切り捨て禁止)。 */
+    onRenderTruncated?: (info: { renderedCells: number; droppedCols: number }) => void
+    /** Vertical callback throttle passthrough (horizontal fires synchronously). / 縦コールバックのスロットル透過 (横は同期発火)。 */
+    callbackThrottleMs?: number
+    /** 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
+     * 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)
+     * を静的 left で直接描画 (W_F は上限 128 × 2^18 = 2^25 で有界 — 実運用は viewport ≪ 2^24)、
+     * スクロール帯の窓探索は W_F
+     * オフセット始まり、残差 transform は −W_F の原点シフト項を持つ。0 以上の整数かつ
+     * MAX_FROZEN_LEADING_COLS 以下 — 違反は RangeError (fail-fast)。現在の colCount を超える
+     * 値は全列凍結 (文書化された動的クランプ — フォールバックではない)。
+     */
+    frozenLeadingCols?: number
+    /**
+     * Number of leading rows pinned at the top (frozen-rows design plan — 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
+     * の外: スクロール行は**シフト済みインデックス空間** (itemCount = rowCount − R、getItem =
+     * i + R) に住み、vy はスクロール帯の論理位置・縦バーは帯を自然に写像する。0 以上の整数
+     * かつ MAX_FROZEN_LEADING_ROWS 以下 — 違反は RangeError (fail-fast)。現在の rowCount を
+     * 超える値は全行凍結 (文書化された動的クランプ — スクロール行は正準空窓 start > end を
+     * 通知しゼロ描画)。
+     */
+    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).
+     * 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]
+     * の整数 — 違反は RangeError (fail-fast)。動的クランプ (文書化契約): min(T, colCount −
+     * effectiveFrozenCols) — カウント空間は**先頭が勝つ**。末尾セルはアンカー機構の外の
+     * 右アンカークリップに帯ローカル left で描画し、`--aqvs-grid-trailing-width` は T > 0 の
+     * ときのみ書かれる。`scrollToCell` / `initialScrollAnchor` の末尾列狙いは横 no-op
+     * (常時可視)。T = 0 は DOM 構造まで従来と恒等。
+     */
+    frozenTrailingCols?: number
+    /**
+     * Number of trailing rows pinned at the bottom (v3.5.0 trailing-freeze plan §3; 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`
+     * 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]
+     * の整数 — 違反は RangeError (fail-fast)。動的クランプ (文書化契約): min(T, rowCount −
+     * effectiveFrozenRows) — 先頭が勝つ。帯はペインの**下**のグリッド所有バンドで、埋め込み
+     * スクロール行は**末尾**だけが伸縮する (itemCount = rowCount − R − T、getItem = i + R
+     * 不変) — T の実行時変更は埋め込み VirtualScroll を再マウントしない (ADR-23)。
+     * `scrollToCell` / `initialScrollAnchor` の末尾行狙いは縦 no-op (常時可視)。T = 0 は
+     * DOM 構造まで従来と恒等。
+     */
+    frozenTrailingRows?: number
+    /** Row-axis overscan (default 3 — a declared, intentional deviation from the bare VirtualScroll default 15; see the bounding contract). / 行軸 overscan (既定 3 — 素の既定 15 からの宣言済み意図的乖離)。 */
+    overscanRows?: number
+    /** Column-axis overscan (default 3). / 列軸 overscan (既定 3)。 */
+    overscanCols?: number
+    /**
+     * Explicit root box size (px) — skips ResizeObserver self-measurement (the row-side
+     * viewportSize explicit-mode twin; deterministic for tests / SSR). The cell viewport is
+     * derived by subtracting the scrollbar thickness on both axes.
+     * ルート箱寸法の明示指定 (px) — RO 自己計測を省略する (行側 viewportSize 明示モードの双子。
+     * テスト / SSR の決定性)。セルビューポートは両軸ともバー厚を差し引いて導出する。
+     */
+    viewportSize?: { width: number; height: number }
+    /** 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
+    scrollBarOptions?: VirtualScrollScrollBarOptions
+    liveRegion?: VirtualGridLiveRegionOptions
+    className?: string
+    testId?: string
+}
+
+/** Imperative handle (logical coordinates everywhere; -1 sentinels pre-attach — row-parity incl. return values). / 命令ハンドル (全て論理座標・未接続 -1 番兵 — 返り値契約まで行側と対称)。 */
+export type VirtualGridHandle = {
+    /**
+     * Jump API — do NOT use for continuous input (use scrollBy). Vertical delegates to the row
+     * scrollTo (which floors and pins a row anchor); horizontal clamps into [0, max] with no
+     * floor and no anchor pinning (the synthetic axis has no pane anchor — depth safety comes
+     * from quantized anchor rebasing instead). Returns the applied clamped position.
+     * ジャンプ API — 連続入力には使わない (scrollBy を使う)。縦は行 scrollTo へ委譲 (floor +
+     * 行アンカー張り)、横は [0, max] クランプのみで floor もアンカー張りも行わない (合成軸に
+     * ペインアンカーは無く、深度安全は量子化アンカー再基準化が担う)。クランプ後位置を返す。
+     */
+    scrollTo(pos: { x?: number; y?: number }): { x: number; y: number }
+    /** Relative float-accumulating path (wheel semantics; returns the applied clamped position — drag loops consume it synchronously). / 相対 float 累積経路 (ホイール同義。クランプ後位置を同期 return — ドラッグループが消費)。 */
+    scrollBy(delta: { x?: number; y?: number }): { x: number; y: number }
+    /**
+     * Cell-targeted jump. alignY uses the row vocabulary (top/bottom/center), alignX its
+     * horizontal twin (start/end/center). No "nearest". Targeting a LEADING frozen or TRAILING
+     * 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.
+     * セル狙いジャンプ。"nearest" は無し。先頭 / 末尾凍結列狙いの横成分は no-op で、既存の
+     * 列アンカーはそのまま残る (視覚的現状維持 — 手動横入力が従来どおり解除する)。先頭 /
+     * 末尾凍結行狙いの縦成分も no-op。帯所属の判定は**呼出し時** — 張った後の T 変更は
+     * ADR-23 のクランプ意味論 (T 増加で末尾帯入りする行を狙った保留行アンカーは最終
+     * スクロール行へクランプ) に従う。重複登記 (ADR-19-1): 先頭 + 末尾の帯寸がビューポートを
+     * 超えるとき、隠れた末尾セルはどのスクロール位置でも可視化できない — 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})。 */
+    getScrollPosition(): { x: number; y: number }
+    /** {index, offset} anchor capture for exact restore; null when either count is 0, or the embedded scroll rows are absent (all-frozen OR a degenerate band whose H_F fills the viewport — both force itemCount 0, so there is no scroll row to anchor). / 厳密復元用アンカー捕獲。どちらかの count が 0、またはスクロール行が不在 (全行凍結 / H_F がビューポートを埋める縮退帯 — いずれも itemCount 0) なら null。 */
+    getScrollAnchor(): { row: number; col: number; offsetX: number; offsetY: number } | null
+    getViewportSize(): { width: number; height: number }
+    getContentSize(): { width: number; height: number }
+    getRange(): VirtualGridRange | null
+    /** Pair-call seam: getRowHeight stays the truth. 3-way split — leading band rows bump the frozen-row epoch, trailing band rows bump the trailing-row epoch (accessor re-read; the bands hold no tree), scroll rows delegate to the row updateItemSize at −R. / 対呼び出しシーム (getRowHeight が正)。3 分岐 — 先頭帯行は凍結行 epoch、末尾帯行は末尾行 epoch の繰上げ (アクセサ再読 — 帯に木は無い)、スクロール行は −R で行 updateItemSize へ委譲。 */
+    updateRowSize(row: number, px: number): void
+    /**
+     * Column twin: validates (MAX_TRACK_SIZE fail-fast), updates the width tree, and bumps the
+     * width epoch so committed cells REPAINT even when the window key is unchanged (small grids,
+     * offsetting batch resizes). Multi-call batch loops coalesce into one recompute via React's
+     * automatic state batching (one commit per synchronous batch — the design's rAF-coalescing
+     * intent realized at commit granularity).
+     * 列双子: 検証 (fail-fast) → 幅木更新 → 幅エポックの繰上げで、窓キー不変でもコミット済み
+     * セルを再描画する (小さなグリッド・相殺バッチリサイズ)。連続呼び出しは React の自動
+     * バッチングで 1 コミットに合流 (設計の rAF 合流意図のコミット粒度での実現)。
+     */
+    updateColSize(col: number, px: number): void
+    /**
+     * Effective frozen-band sizes on both axes and both ends (v3.5.0 — a non-breaking field
+     * extension of the {cols, width} → {cols, width, rows, height} precedent). cols/rows/
+     * trailingCols/trailingRows = dynamic post-clamp counts; width/height/trailingWidth/
+     * trailingHeight = TREE px (the trailing sizes are tree SUFFIX sums); trailingVisibleWidth/
+     * trailingVisibleHeight = viewport-clipped `min(tree, max(0, viewport − leading))` — THE
+     * single source for W_T_vis / H_T_vis that every consumer judgment/write path cites (never
+     * re-derive the formula). Pre-attach the grid viewport reads {0, 0}, so the vis fields are
+     * 0 (an initial measured state, not a sentinel) while the tree fields stay tree px.
+     * 実効凍結帯寸法 — 両軸・両端 (v3.5.0。{cols, width} → {cols, width, rows, height} の
+     * 前例に続く非破壊のフィールド追加)。cols / rows / trailingCols / trailingRows は動的
+     * クランプ後の実効カウント、width / height / trailingWidth / trailingHeight は**木** px
+     * (末尾寸は木の接尾辞和)、trailingVisibleWidth / trailingVisibleHeight はビューポート
+     * クリップ `min(木, max(0, viewport − 先頭))` — W_T_vis / H_T_vis の**単一情報源**で、
+     * 消費側の判定 / 書込み経路は全てこのフィールドを名指しで読む (式の再導出禁止)。
+     * プレアタッチはビューポート {0, 0} のため vis フィールドは 0 (番兵ではなく初期実測状態)、
+     * 木フィールドは常に木 px。
+     */
+    getFrozenSize(): { cols: number; width: number; rows: number; height: number; trailingCols: number; trailingRows: number; trailingWidth: number; trailingHeight: number; trailingVisibleWidth: number; trailingVisibleHeight: number }
+    /** 2-axis wheel bridge entry: vertical → embedded VirtualScroll, horizontal → hx. Returns whether the event was consumed (WheelBridgeTarget contract). / 2 軸ホイールブリッジ口。消費有無を返す (ブリッジ契約)。 */
+    applyWheel(event: WheelEvent): boolean
+    /** Focuses the row wrapper at `row` (scroll rows via the −R-shifted row-side focusItemAtIndex — enableKeyboardNavigation applies; frozen band rows are focused directly and need no option). / 行ラッパーへフォーカス (スクロール行は −R シフトの行側 focusItemAtIndex — enableKeyboardNavigation が前提。凍結帯行は直接フォーカスでオプション不要)。 */
+    focusRowAtIndex(row: number, options?: { ensureVisible?: boolean }): void
+}
+
+/**
+ * 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).
+ *
+ * 消費側アクセサのトラックサイズ検証: [0, MAX_TRACK_SIZE] の有限整数。違反は RangeError
+ * (fail-fast — 幅木は遅延具現化のため render 中の throw もあり得る契約違反として error
+ * boundary へ)。
+ */
+const validateTrackSize = (value: number, axis: "row" | "col", index: number): number => {
+    if (!(Number.isInteger(value) && value >= 0 && value <= MAX_TRACK_SIZE)) {
+        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).`,
+        )
+    }
+    return value
+}
+
+/**
+ * Computes the column placement for one horizontal position: the rendering/visible ranges via
+ * the SHARED computeRenderingRanges (identical function to the row axis, huge branch included)
+ * plus the quantized column anchor. The anchor rebases only when the RENDERING-window start
+ * (overscan inclusive — the exact row-side basis) drifts beyond ANCHOR_REBASE_DISTANCE, so cell
+ * `left` (= absolute − anchor) and the wrapper residual stay small at any depth. Pure — exported
+ * as the primary mutation-gate surface.
+ *
+ * 1 つの横位置に対する列配置の算出: 共有 computeRenderingRanges (行軸と同一関数、huge 分岐
+ * 込み) による範囲 + 量子化列アンカー。アンカーは**描画窓 (オーバースキャン込み) 先頭**が
+ * ANCHOR_REBASE_DISTANCE を超えて離れたときだけ付替える (行側と同一基準) — セル left
+ * (= 絶対 − アンカー) と残差が任意深度で小さく保たれる。純関数 — 変異ゲートの主面として export。
+ */
+export const computeColumnPlacement = (
+    hx: number,
+    viewportWidth: number,
+    overscanCols: number,
+    colCount: number,
+    getColWidth: (col: number) => number,
+    colTree: ReturnType<typeof useFenwickMapTree>,
+    totalWidth: number,
+    prevAnchor: number,
+): { renderingColStart: number; renderingColEnd: number; visibleColStart: number; visibleColEnd: number; colAnchor: number } => {
+    const ranges = computeRenderingRanges(hx, viewportWidth, overscanCols, colCount, getColWidth, colTree, totalWidth)
+    if (colCount === 0) {
+        return { renderingColStart: 0, renderingColEnd: 0, visibleColStart: 0, visibleColEnd: 0, colAnchor: 0 }
+    }
+    // アンカー再基準化 (行 memo と同一ロジック): 描画窓先頭の絶対 X が現アンカーから距離超過の
+    // ときのみ付替え。付替え先は任意座標 (グリッド量子化ではなくトリガー距離 — 付録 A.2)
+    const safeStart = minmax(ranges.renderingStartIndex, 0, colCount - 1)
+    const { cumulative, currentValue } = colTree.prefixSum(safeStart, { materializeOption: { materialize: false } })
+    const startPosition = cumulative - currentValue
+    const colAnchor = Number.isFinite(startPosition) && Math.abs(startPosition - prevAnchor) > ANCHOR_REBASE_DISTANCE ? startPosition : prevAnchor
+    return {
+        renderingColStart: ranges.renderingStartIndex,
+        renderingColEnd: ranges.renderingEndIndex,
+        visibleColStart: ranges.visibleStartIndex,
+        visibleColEnd: ranges.visibleEndIndex,
+        colAnchor,
+    }
+}
+
+/** One placed column: index + content-absolute left + width. / 配置済み列 1 本: index + コンテンツ絶対 left + 幅。 */
+type PlacedColumn = { col: number; left: number; width: number }
+
+/** Stable empty placement (identity-stable for the F = 0 default path). / 安定空配置 (F = 0 既定経路の identity 安定用)。 */
+const EMPTY_PLACED_COLUMNS: PlacedColumn[] = []
+
+/**
+ * Enumerates the visible (width > 0) columns of a rendering window ONCE per placement, with
+ * content-absolute lefts, self-healing width deltas (getColWidth is the truth — tree deviations
+ * inside the window are collected for a batched update, the row-side reconciliation twin), and
+ * zero-width runs jumped in O(log n) past the SHARED ZERO_HEIGHT_RUN_LIMIT (imported from the
+ * row axis — no duplicated constant, same `>` trigger).
+ *
+ * 描画窓の可視 (幅 > 0) 列を配置ごとに 1 回列挙する: コンテンツ絶対 left、幅の自己修復差分
+ * (getColWidth が正 — 窓内の木との乖離をバッチ更新用に収集、行側照合の双子)、幅 0 ランは
+ * 行軸から import した共有 ZERO_HEIGHT_RUN_LIMIT 超 (`>` — 比較まで同一) で O(log n) ジャンプ。
+ */
+const collectVisibleColumns = (startCol: number, endCol: number, getColWidth: (col: number) => number, colTree: ReturnType<typeof useFenwickMapTree>, maxColumns: number): { columns: PlacedColumn[]; widthUpdates: Array<{ index: number; value: number }>; truncated: number } => {
+    const columns: PlacedColumn[] = []
+    const widthUpdates: Array<{ index: number; value: number }> = []
+    if (endCol < startCol) {
+        return { columns, widthUpdates, truncated: 0 }
+    }
+    const startPrefix = colTree.prefixSum(startCol, { materializeOption: { materialize: false } })
+    // 窓先頭の絶対 left から幅を積む O(k) 走査 (列ごとの prefixSum O(k·log n) を回避 — 行 memo と同型)
+    let runningLeft = startPrefix.cumulative - startPrefix.currentValue
+    let zeroRun = 0
+    let i = startCol
+    while (i <= endCol) {
+        if (columns.length >= maxColumns) {
+            // 打切り列数 = 残り index 数 (可視/非可視を問わず未走査分)
+            return { columns, widthUpdates, truncated: endCol - i + 1 }
+        }
+        const width = getColWidth(i)
+        const cached = colTree.get(i)
+        if (width !== cached) {
+            widthUpdates.push({ index: i, value: width })
+        }
+        if (width > 0) {
+            columns.push({ col: i, left: runningLeft, width })
+            runningLeft += cached
+            zeroRun = 0
+            i += 1
+            continue
+        }
+        runningLeft += cached
+        zeroRun += 1
+        i += 1
+        if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
+            // 幅 0 ランの Fenwick ジャンプ (行側と共有定数・同一比較 `>` — 複製禁止): 次の非 0 列へ。
+            // +0.5 は右開区間バンプ — 木側の値で跳ぶため self-heal 前の乖離があっても有界性は保たれる
+            const jump = colTree.findIndexAtOrAfter(runningLeft + 0.5, { materializeOption: { materialize: false } })
+            if (jump.index === -1 || jump.index <= i || !Number.isSafeInteger(jump.index)) {
+                break
+            }
+            const jumpPrefix = colTree.prefixSum(jump.index, { materializeOption: { materialize: false } })
+            runningLeft = jumpPrefix.cumulative - jumpPrefix.currentValue
+            i = jump.index
+            zeroRun = 0
+        }
+    }
+    return { columns, widthUpdates, truncated: 0 }
+}
+
+/**
+ * Enumerates the frozen band (design §8): columns [0, frozenCols) with DIRECT tree-absolute
+ * lefts (no anchor subtraction — the band sits outside the anchor machinery; W_F is bounded
+ * by 128 x MAX_TRACK_SIZE = 2^25, practically <= viewport << 2^24), zero-width columns skipped (no DOM — the shared hidden-track
+ * discipline), and width self-heal deltas collected under the same tree-is-position /
+ * accessor-is-width split as collectVisibleColumns. Returns W_F = the TREE prefix width of the
+ * band (the scroll band's coordinate origin — heals converge the two).
+ *
+ * 凍結帯の列挙 (設計 §8): 列 [0, frozenCols) を木絶対 left の直接値で並べ (アンカー減算なし —
+ * 帯はアンカー機構の外。W_F は 128 × 2^18 = 2^25 で有界、実運用 ≤ viewport ≪ 2^24)、幅 0 列は DOM 非生成
+ * (非表示トラックの共有規律)、幅 self-heal 差分は collectVisibleColumns と同じ
+ * 「位置は木・幅はアクセサ」分担で収集する。返す W_F は帯の**木**接頭辞幅 (スクロール帯の
+ * 座標原点 — 治癒が両者を収束させる)。
+ */
+const collectFrozenColumns = (frozenCols: number, getColWidth: (col: number) => number, colTree: ReturnType<typeof useFenwickMapTree>): { columns: PlacedColumn[]; widthUpdates: Array<{ index: number; value: number }>; width: number } => {
+    const columns: PlacedColumn[] = []
+    const widthUpdates: Array<{ index: number; value: number }> = []
+    let runningLeft = 0
+    // F ≤ MAX_FROZEN_LEADING_COLS のため素朴な O(F) 走査で十分 (幅 0 ジャンプ機構は不要)
+    for (let col = 0; col < frozenCols; col += 1) {
+        const width = getColWidth(col)
+        const cached = colTree.get(col)
+        if (width !== cached) {
+            widthUpdates.push({ index: col, value: width })
+        }
+        if (width > 0) {
+            columns.push({ col, left: runningLeft, width })
+        }
+        runningLeft += cached
+    }
+    return { columns, widthUpdates, width: runningLeft }
+}
+
+/**
+ * Enumerates the trailing frozen band (v3.5.0 trailing-freeze plan §6.1-5 — the suffix twin of
+ * collectFrozenColumns): columns [colCount − trailingCols, colCount) with BAND-LOCAL lefts (a
+ * running prefix that starts at 0 — the right-anchored inner owns the placement, so trailing
+ * cells never take the anchor subtraction; W_T is bounded by 128 x MAX_TRACK_SIZE = 2^25),
+ * zero-width columns skipped (no DOM — the shared hidden-track discipline), and width
+ * self-heal deltas collected under the same tree-is-position / accessor-is-width split as
+ * collectVisibleColumns. Returns width = W_T, the TREE suffix width of the band.
+ *
+ * 末尾凍結帯の列挙 (3.5.0 末尾凍結プラン §6.1-5 — collectFrozenColumns の接尾辞双子)。列
+ * [colCount − trailingCols, colCount) を**帯ローカル** left (0 始まりの running 接頭辞 —
+ * 配置は右アンカー inner が担い、末尾セルはアンカー減算を決して取らない。W_T は 128 × 2^18 =
+ * 2^25 で有界) で並べ、幅 0 列は DOM 非生成 (非表示トラックの共有規律)、幅 self-heal 差分は
+ * collectVisibleColumns と同じ「位置は木・幅はアクセサ」分担で収集する。返す width = W_T
+ * (帯の**木**接尾辞幅)。
+ */
+const collectTrailingColumns = (colCount: number, trailingCols: number, getColWidth: (col: number) => number, colTree: ReturnType<typeof useFenwickMapTree>): { columns: PlacedColumn[]; widthUpdates: Array<{ index: number; value: number }>; width: number } => {
+    const columns: PlacedColumn[] = []
+    const widthUpdates: Array<{ index: number; value: number }> = []
+    let runningLeft = 0
+    // T ≤ MAX_FROZEN_TRAILING_COLS のため素朴な O(T) 走査で十分 (幅 0 ジャンプ機構は不要)
+    for (let col = colCount - trailingCols; col < colCount; col += 1) {
+        const width = getColWidth(col)
+        const cached = colTree.get(col)
+        if (width !== cached) {
+            widthUpdates.push({ index: col, value: width })
+        }
+        if (width > 0) {
+            columns.push({ col, left: runningLeft, width })
+        }
+        runningLeft += cached
+    }
+    return { columns, widthUpdates, width: runningLeft }
+}
+
+/**
+ * THE single JS source for W_T_vis / H_T_vis (v3.5.0 trailing-freeze plan §2.1-4): clips a
+ * trailing band's TREE extent to what the viewport can show after the leading band took its
+ * share — `min(trailing, max(0, viewport − leading))`. Consumers are exactly three: the
+ * trailing-rows band template height, the hbar paddingRight, and the getFrozenSize
+ * trailingVisibleWidth/Height export. Never re-derive the formula elsewhere (the CSS max()
+ * left edge of `.aqvs-grid-row-trailing` is the registered calc() equivalent — the ONLY
+ * exception, annotated in the stylesheet).
+ *
+ * W_T_vis / H_T_vis の**単一 JS 源** (3.5.0 末尾凍結プラン §2.1-4)。末尾帯の**木**寸を
+ * 「先頭帯が取った残り」へクリップする `min(末尾, max(0, viewport − 先頭))`。消費先は
+ * 末尾行帯テンプレート高 / hbar paddingRight / getFrozenSize の vis export の 3 点ちょうど —
+ * 式を他所へ複製しない (`.aqvs-grid-row-trailing` の CSS max() 左端だけが登記済みの calc()
+ * 等価形で、スタイルシート側にインライン登記済み)。
+ */
+const trailingVisibleSize = (trailingSize: number, frozenSize: number, viewportSize: number): number => Math.min(trailingSize, Math.max(0, viewportSize - frozenSize))
+
+/** Internal committed column-window state (anchor rides with the window — the M10 coherence unit). / コミット済み列窓状態 (アンカーは窓と一体 — M10 整合の単位)。 */
+type ColumnWindowState = {
+    renderingColStart: number
+    renderingColEnd: number
+    visibleColStart: number
+    visibleColEnd: number
+    colAnchor: number
+    /** Monotonic key for cheap bail comparisons. / 安価な bail 比較用の合成キー。 */
+    key: string
+}
+
+const INITIAL_COLUMN_WINDOW: ColumnWindowState = { renderingColStart: 0, renderingColEnd: 0, visibleColStart: 0, visibleColEnd: 0, colAnchor: 0, key: "0:0:0" }
+
+/**
+ * VirtualGrid implementation. The vertical axis is the embedded VirtualScroll (unchanged
+ * machinery); the horizontal axis mirrors it: logical hx in a float64 ref, the residual as a
+ * root-scoped CSS variable (`--aqvs-grid-hx-residual` — written at ONE site) consumed by the
+ * grid-owned `.aqvs-grid-row` translateX — or, in frozen mode (v3.3.0), by
+ * `.aqvs-grid-row-scroll-inner`'s calc(residual − W_F) while the host row stays static —
+ * (package CSS — deliberately NOT via contentProps className, which would clobber the pane's
+ * structural class), and the committed column window
+ * + anchor as React state so cells and the residual always switch in the same commit (the
+ * layout effect below writes the residual for the committed anchor pre-paint — the M10
+ * no-tearing invariant).
+ *
+ * VirtualGrid 実装。縦軸は内包 VirtualScroll (機構無変更)、横軸はその鏡像: 論理 hx は
+ * float64 ref、残差はルートの CSS 変数 `--aqvs-grid-hx-residual` (書き手 1 点) をグリッド
+ * 所有の `.aqvs-grid-row` translateX — 凍結モード (v3.3.0) では `.aqvs-grid-row-scroll-inner`
+ * の calc(残差 − W_F) — が消費 (パッケージ CSS — contentProps className 経由は
+ * ペイン構造クラスを破壊するため意図的に不採用)、コミット済み列窓 + アンカーは React state —
+ * セルと残差が常に同一コミットで切替わる (下の layout effect がコミット済みアンカーの残差を
+ * paint 前に書く = M10 の非 tearing 不変条件)。
+ */
+const VirtualGridInner = <T,>(
+    {
+        rowCount,
+        colCount,
+        getRowHeight,
+        getColWidth,
+        getCell,
+        getCellKey,
+        children,
+        getCellProps,
+        getRowProps,
+        contentProps,
+        background,
+        contentInsets,
+        onRowFocus,
+        frozenLeadingCols = 0,
+        frozenLeadingRows = 0,
+        frozenTrailingCols = 0,
+        frozenTrailingRows = 0,
+        horizontalKeyInputs,
+        horizontalKeyStep,
+        onScroll,
+        onRangeChange,
+        onRenderTruncated,
+        callbackThrottleMs,
+        initialScrollAnchor,
+        overscanRows = DEFAULT_GRID_OVERSCAN,
+        overscanCols = DEFAULT_GRID_OVERSCAN,
+        viewportSize,
+        __maxRenderedCells,
+        behaviorOptions,
+        scrollBarOptions,
+        liveRegion,
+        className,
+        testId,
+    }: VirtualGridProps<T>,
+    ref: React.Ref<VirtualGridHandle>,
+): ReactNode => {
+    const scrollHandleRef = useRef<VirtualScrollHandle | null>(null)
+    const rootRef = useRef<HTMLDivElement | null>(null)
+
+    // ---- 検証つきアクセサ (identity は既定で安定 — ref 経由で最新を読む)。resetOn* 指定時のみ
+    //      素のアクセサ identity を意図的に踏襲する: 内包 VirtualScroll / 幅木の再構築キーは
+    //      アクセサ identity のため、恒久固定ラッパーでは reset が構造的に発火しない ----
+    const getRowHeightRef = useRef(getRowHeight)
+    getRowHeightRef.current = getRowHeight
+    const getColWidthRef = useRef(getColWidth)
+    getColWidthRef.current = getColWidth
+    const resetOnGetColWidthChange = behaviorOptions?.resetOnGetColWidthChange === true
+    const resetOnGetRowHeightChange = behaviorOptions?.resetOnGetItemHeightChange === true
+    const rowHeightIdentity = resetOnGetRowHeightChange ? getRowHeight : null
+    const colWidthIdentity = resetOnGetColWidthChange ? getColWidth : null
+    const validatedGetRowHeight = useCallback(
+        (row: number) => {
+            void rowHeightIdentity
+            return validateTrackSize(getRowHeightRef.current(row), "row", row)
+        },
+        [rowHeightIdentity],
+    )
+    const validatedGetColWidth = useCallback(
+        (col: number) => {
+            void colWidthIdentity
+            return validateTrackSize(getColWidthRef.current(col), "col", col)
+        },
+        [colWidthIdentity],
+    )
+
+    // ---- 列幅木 (M1/M2 の第 2 インスタンス — 疎 Map + baseValue サンプリング O(100) + 遅延具現化)。
+    //      §10.4 の render-phase 変異契約を継承: valueOrFn / options の identity 安定が必須
+    //      (resetOn* 指定時の identity 変化は意図的な再構築トリガー) ----
+    const defaultColWidth = behaviorOptions?.defaultColWidth
+    const colTreeOptions = useMemo(() => {
+        // defaultColWidth はトラックサイズと同じ検査 (fail-fast — 不正な見積り値で総幅を汚染しない)
+        if (defaultColWidth !== undefined && !(Number.isInteger(defaultColWidth) && defaultColWidth >= 0 && defaultColWidth <= MAX_TRACK_SIZE)) {
+            throw new RangeError(`[VirtualGrid] behaviorOptions.defaultColWidth must be an integer in [0, ${MAX_TRACK_SIZE}], received ${defaultColWidth}.`)
+        }
+        return { resetOnValueFnChange: resetOnGetColWidthChange, baseValue: defaultColWidth }
+    }, [resetOnGetColWidthChange, defaultColWidth])
+    const colTree = useFenwickMapTree(colCount, validatedGetColWidth, colTreeOptions)
+
+    // ---- 幅エポック (木の内容バージョン): updateColSize / self-heal 適用で繰上げ、窓キー不変でも
+    //      配置 memo と列窓再計算を失効させる。行側は総高 (contentSize) を反応辺にするが、相殺
+    //      バッチリサイズ (総和不変) も拾えるようエポックはその厳密上位互換 ----
+    const [widthEpoch, setWidthEpoch] = useState(0)
+
+    // ---- 凍結帯 (設計 §8) — 形状検証は fail-fast、colCount 超過だけは動的クランプ (シート
+    //      切替の過渡で colCount が一時 0 になる正当構成を throw で殺さないための文書化契約) ----
+    if (!(Number.isInteger(frozenLeadingCols) && frozenLeadingCols >= 0 && frozenLeadingCols <= MAX_FROZEN_LEADING_COLS)) {
+        throw new RangeError(`[VirtualGrid] frozenLeadingCols must be an integer in [0, ${MAX_FROZEN_LEADING_COLS}], received ${frozenLeadingCols}.`)
+    }
+    const effectiveFrozenCols = Math.min(frozenLeadingCols, colCount)
+    /** Fresh W_F for drag loops / clamps (mirrored from the frozen memo each render). / ドラッグループ / クランプ用の鮮度 W_F (凍結 memo から毎レンダー写像)。 */
+    const frozenWidthRef = useRef(0)
+
+    // ---- 末尾凍結列帯 (3.5.0 プラン §6.1-3) — 先頭側と同文の fail-fast。動的クランプは
+    //      min(T, colCount − 先頭実効) で**先頭がカウント空間で勝つ** (ADR-19-1 の文書化契約) ----
+    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}.`)
+    }
+    const effectiveTrailingCols = Math.min(frozenTrailingCols, colCount - effectiveFrozenCols)
+    /** Fresh W_T for drag loops / clamps (mirrored from the trailing memo each render). / ドラッグループ / クランプ用の鮮度 W_T (末尾 memo から毎レンダー写像)。 */
+    const trailingWidthRef = useRef(0)
+
+    // ---- 凍結行帯 (行凍結設計 §4-1) — 列と同文の fail-fast + 動的クランプ ----
+    if (!(Number.isInteger(frozenLeadingRows) && frozenLeadingRows >= 0 && frozenLeadingRows <= MAX_FROZEN_LEADING_ROWS)) {
+        throw new RangeError(`[VirtualGrid] frozenLeadingRows must be an integer in [0, ${MAX_FROZEN_LEADING_ROWS}], received ${frozenLeadingRows}.`)
+    }
+    const effectiveFrozenRows = Math.min(frozenLeadingRows, rowCount)
+
+    // ---- 末尾凍結行帯 (3.5.0 プラン §6.1-3) — 列側と同文の fail-fast + 先頭勝ちクランプ ----
+    if (!(Number.isInteger(frozenTrailingRows) && frozenTrailingRows >= 0 && frozenTrailingRows <= MAX_FROZEN_TRAILING_ROWS)) {
+        throw new RangeError(`[VirtualGrid] frozenTrailingRows must be an integer in [0, ${MAX_FROZEN_TRAILING_ROWS}], received ${frozenTrailingRows}.`)
+    }
+    const effectiveTrailingRows = Math.min(frozenTrailingRows, rowCount - effectiveFrozenRows)
+    /** Scroll-row count in the SHIFTED space (design §2; the tail loses T — the embedded VirtualScroll's itemCount). / シフト空間のスクロール行数 (末尾は −T — 埋め込み VirtualScroll の itemCount)。 */
+    const scrollRowCount = Math.max(0, rowCount - effectiveFrozenRows - effectiveTrailingRows)
+    /** Degenerate-band flag ref (H_F >= measured viewport — §3.3 の縮退帯と同じ正準空窓へ). / 縮退帯フラグ ref (H_F ≥ 実測ビューポート — §3.3 縮退帯と同じ正準空窓)。 */
+    const degenerateBandRef = useRef(false)
+    /** Fresh H_F for handle reads (mirrored from the band memo each render). / ハンドル読み用の鮮度 H_F (帯 memo から毎レンダー写像)。 */
+    const frozenHeightRef = useRef(0)
+    /** Fresh H_T for handle reads (mirrored from the trailing band memo each render). / ハンドル読み用の鮮度 H_T (末尾帯 memo から毎レンダー写像)。 */
+    const trailingHeightRef = useRef(0)
+
+    // ---- 凍結行帯の列挙 (行凍結設計 §4-2) — グリッド所有の帯外バンド。行高の真実は
+    //      アクセサ直読 (列帯と違い第 2 の格納庫 = 木 が無いためヒール機構は不要 — 更新経路は
+    //      updateRowSize の epoch 繰上げとアクセサ identity 変化のみ)。高さ 0 行は DOM 非生成 ----
+    const [frozenRowEpoch, setFrozenRowEpoch] = useState(0)
+    const { frozenRows, frozenHeight } = useMemo(() => {
+        void frozenRowEpoch
+        if (effectiveFrozenRows === 0) {
+            return { frozenRows: [] as Array<{ row: number; top: number; height: number }>, frozenHeight: 0 }
+        }
+        const rows: Array<{ row: number; top: number; height: number }> = []
+        let running = 0
+        for (let row = 0; row < effectiveFrozenRows; row += 1) {
+            const height = validatedGetRowHeight(row)
+            if (height > 0) {
+                rows.push({ row, top: running, height })
+            }
+            running += height
+        }
+        return { frozenRows: rows, frozenHeight: running }
+    }, [effectiveFrozenRows, frozenRowEpoch, validatedGetRowHeight])
+    frozenHeightRef.current = frozenHeight
+
+    // ---- 末尾行帯の列挙 (3.5.0 プラン §6.1-11) — 先頭行帯と同形の帯外バンド。木もヒール機構も
+    //      持たない (アクセサが唯一の真実 — 先頭行帯の宣言済み非対称と同文)。top は帯ローカル
+    //      接頭辞和 (inner の bottom 定着が右アンカーの行版を担う)。高さ 0 行は DOM 非生成 ----
+    const [trailingRowEpoch, setTrailingRowEpoch] = useState(0)
+    const { trailingRows, trailingHeight } = useMemo(() => {
+        void trailingRowEpoch
+        if (effectiveTrailingRows === 0) {
+            return { trailingRows: [] as Array<{ row: number; top: number; height: number }>, trailingHeight: 0 }
+        }
+        const rows: Array<{ row: number; top: number; height: number }> = []
+        let running = 0
+        for (let row = rowCount - effectiveTrailingRows; row < rowCount; row += 1) {
+            const height = validatedGetRowHeight(row)
+            if (height > 0) {
+                rows.push({ row, top: running, height })
+            }
+            running += height
+        }
+        return { trailingRows: rows, trailingHeight: running }
+    }, [effectiveTrailingRows, rowCount, trailingRowEpoch, validatedGetRowHeight])
+    trailingHeightRef.current = trailingHeight
+    /** Shifted row-height accessor for the embedded VirtualScroll (design §2). / 埋め込み VirtualScroll 用のシフト済み行高アクセサ (設計 §2)。 */
+    const scrollGetRowHeight = useCallback((index: number) => validatedGetRowHeight(index + effectiveFrozenRows), [validatedGetRowHeight, effectiveFrozenRows])
+    // 行フォーカス通知はフル行空間へ +R 翻訳する (シフト漏れの是正 — 素通しは R > 0 でフル行 r の
+    // フォーカスを r − R として報告してしまう)。identity は [effectiveFrozenRows] のみで安定化する
+    // — インラインアロー直渡しは毎レンダーで prop identity を変え、内包側 handleItemFocus 経由で
+    // React.memo VirtualScrollItem の全行を再レンダーさせる (横スクロールの setBarHx 毎 rAF で発火。
+    // R2 是正)。onRowFocus は ref 経由で読み、その identity 変化を deps に含めない
+    const onRowFocusRef = useRef(onRowFocus)
+    onRowFocusRef.current = onRowFocus
+    const hasRowFocus = onRowFocus !== undefined
+    const shiftedRowFocus = useMemo(() => (hasRowFocus ? (index: number) => onRowFocusRef.current?.(index + effectiveFrozenRows) : undefined), [effectiveFrozenRows, hasRowFocus])
+    /** Reactive key for H_F consumers (memo edge — the ref alone would not invalidate). / H_F 消費 memo の反応辺キー (ref 直読は失効しない)。 */
+    const frozenHeightEpochKey = frozenHeight
+    /** Reactive key for H_T consumers (the trailing twin). / H_T 消費 memo の反応辺キー (末尾双子)。 */
+    const trailingHeightEpochKey = trailingHeight
+
+    // ---- R の実行時変更 (R1 是正): シフト空間の再ペアリングは埋め込み木にとって「中間削除」で、
+    //      木の changeSize (末尾意味論) では歪む (実測 +228px の総高汚染)。key 再マウントで木を
+    //      作り直し、可視先頭アンカーをフル行空間で持ち越して復元する (視点保存) ----
+    const [prevFrozenRows, setPrevFrozenRows] = useState(effectiveFrozenRows)
+    const toggleAnchorRef = useRef<{ row: number; offsetPx: number } | null>(null)
+    // トグル発生フラグ (捕捉値とは独立の三状態化 — R2 是正): 一度でもトグルすれば、以後は
+    // マウント時 initialScrollAnchor props を絶対に再適用しない。捕捉が null (退場側 itemCount 0 =
+    // 全行凍結 / 縮退帯 / rowCount 過渡 0) でも props へ落ちず undefined (先頭) にする — さもなくば
+    // 消費済みのマウントアンカーが key 再マウントで蘇り視点がテレポートする (実測 y=1200)
+    const toggledRef = useRef(false)
+    if (prevFrozenRows !== effectiveFrozenRows) {
+        setPrevFrozenRows(effectiveFrozenRows)
+        toggledRef.current = true
+        // 旧 R 空間の内包側アンカーを捕捉し、フル行空間へ +旧R で翻訳して保存 (render 中の
+        // ref 書きは derived-state パターンの捕捉 — 同コミットの key 再マウントだけが消費する)
+        const innerAnchor = scrollHandleRef.current?.getScrollAnchor() ?? null
+        toggleAnchorRef.current = innerAnchor === null ? null : { row: innerAnchor.index + prevFrozenRows, offsetPx: innerAnchor.offsetPx }
+    }
+
+    // ---- 論理位置 (float64 ref — DOM へは書かない) と鮮度序列 ----
+    const hxRef = useRef(0)
+    const vyRef = useRef(0)
+    const attachedRef = useRef(false)
+
+    // ---- コミット済み列窓 + アンカー (M10 整合の単位) ----
+    const [columnWindow, setColumnWindow] = useState<ColumnWindowState>(INITIAL_COLUMN_WINDOW)
+    const columnWindowRef = useRef(columnWindow)
+    columnWindowRef.current = columnWindow
+    /** Anchor the DOM currently shows (updated post-commit in the layout effect). / DOM が現在表示中のアンカー (commit 後の layout effect で更新)。 */
+    const committedAnchorRef = useRef(0)
+
+    const [totalWidth, setTotalWidth] = useState(() => colTree.getTotal() ?? 0)
+    const totalWidthRef = useRef(totalWidth)
+    totalWidthRef.current = totalWidth
+    /** Mirrors the tree total into state+ref immediately (same tick — drag loops clamp fresh). / 木総幅を state + ref へ即時反映 (同 tick — ドラッグループが新鮮にクランプ)。 */
+    const commitTotalWidth = useCallback((total: number | undefined) => {
+        // undefined 分岐は木 API の宣言型 (`number | undefined`) 由来。isFinite は正常経路で
+        // 反証不能な防御分岐 (木は入力を事前検証する) — §7 に未検証防御として記録
+        if (typeof total === "number" && Number.isFinite(total)) {
+            totalWidthRef.current = total
+            setTotalWidth(total)
+        }
+    }, [])
+    // ---- 総幅と木の恒常同期: colCount 変化・0 → N 伸長・resetOn* 再構築は木を作り替えるが、
+    //      state はそれを自動では知らない。毎コミットの bail つき照合で木総幅 (真実) へ追随する ----
+    useLayoutEffect(() => {
+        const total = colTree.getTotal()
+        if (typeof total === "number" && Number.isFinite(total) && total !== totalWidthRef.current) {
+            commitTotalWidth(total)
+        }
+    })
+
+    // ---- ビューポート実測 (RO — 縦バー幅ぶんを列窓から差し引く) ----
+    const scrollBarWidth = scrollBarOptions?.width ?? 12
+    const explicitViewport = viewportSize === undefined ? null : { width: Math.max(0, Math.round(viewportSize.width) - scrollBarWidth), height: Math.max(0, Math.round(viewportSize.height) - scrollBarWidth) }
+    const [measuredViewport, setMeasuredViewport] = useState({ width: 0, height: 0 })
+    const viewport = explicitViewport ?? measuredViewport
+    const viewportRef = useRef(viewport)
+    viewportRef.current = viewport
+    /** Degenerate band: H_F + H_T fills the measured viewport — scroll rows go canonical-EMPTY (§3.3 縮退帯の縦対称; 3.5.0 で −H_T を一般化). / 縮退帯: H_F + H_T が実測ビューポートを食い尽くす — スクロール行は正準空窓 (§3.3 の縦対称。3.5.0 で −H_T を一般化)。 */
+    const degenerateBand = viewport.height > 0 && viewport.height - frozenHeight - trailingHeight <= 0
+    degenerateBandRef.current = degenerateBand
+    const hasExplicitViewport = explicitViewport !== null
+    useLayoutEffect(() => {
+        if (hasExplicitViewport) {
+            return
+        }
+        const root = rootRef.current
+        if (root === null) {
+            return
+        }
+        const measure = () => {
+            // ❗ 論理 (レイアウト) px で測る — getBoundingClientRect は祖先 transform scale 下で
+            // 視覚 px (論理 × z) を返し、ズームホストで窓寸・クランプ・列窓の全幾何が z 倍へ歪む。
+            // clientWidth / clientHeight は transform 非影響のレイアウト px (行側 ScrollPane の
+            // 自己計測と同じ座標系)
+            const width = Math.max(0, Math.round(root.clientWidth) - scrollBarWidth)
+            const height = Math.max(0, Math.round(root.clientHeight) - scrollBarWidth)
+            setMeasuredViewport((prev) => (prev.width === width && prev.height === height ? prev : { width, height }))
+        }
+        measure()
+        const observer = new ResizeObserver(measure)
+        observer.observe(root)
+        return () => observer.disconnect()
+    }, [scrollBarWidth, hasExplicitViewport])
+
+    // ---- 残差 var の書き手 (1 点)。コミット済みアンカー基準 — スクロール中の中間フレームでも
+    //      セル left (コミット済みアンカー) と常に同一基準で整合する ----
+    const writeResidual = useCallback(() => {
+        const root = rootRef.current
+        if (root === null) {
+            return
+        }
+        root.style.setProperty("--aqvs-grid-hx-residual", `${committedAnchorRef.current - hxRef.current}px`)
+    }, [])
+
+    /**
+     * Fresh scroll-band width from refs (v3.5.0 trailing-freeze plan §6.1-6 — the ONE ref-space
+     * source): viewport minus BOTH band extents. Replaces the three former inline
+     * `max(0, viewport − W_F)` sites (applyHx / refreshColumns / resolveColumnAnchorHx) so a
+     * W_T change can never go stale in just one of them. T = 0 reduces to the pre-trailing form.
+     * ref 空間のスクロール帯幅 (3.5.0 末尾凍結プラン §6.1-6 — ref 面の単一源)。viewport から
+     * 両端の帯寸を控除する。旧 3 箇所のインライン `max(0, viewport − W_F)` を置換し、W_T 変化が
+     * 1 箇所だけ stale 化する余地を構造的に断つ。T = 0 は従来式へ恒等縮退。
+     */
+    const scrollBandWidthRef = useCallback(() => Math.max(0, viewportRef.current.width - frozenWidthRef.current - trailingWidthRef.current), [])
+
+    // ---- 列窓の再計算 (setState は窓 / アンカー変化時のみ — key 比較で bail) ----
+    const refreshColumns = useCallback(() => {
+        // 凍結帯 (§8-a): 窓探索は木座標 W_F + hx 始まり・帯幅 = viewport − W_F − W_T (3.5.0 一般化)
+        const bandWidth = scrollBandWidthRef()
+        const placement = computeColumnPlacement(frozenWidthRef.current + hxRef.current, bandWidth, overscanCols, colCount, validatedGetColWidth, colTree, totalWidthRef.current, columnWindowRef.current.colAnchor)
+        // 幅 0 の凍結列があると indexAt(W_F + hx) が F 未満へ届く — スクロール窓に凍結列を
+        // 再出現させない床クランプ (§8-c: 凍結帯の描画は凍結 subtree の専有)。床は F そのもの:
+        // 全列凍結 (F ≥ colCount) では start = colCount > end となり、start > end = 空窓が
+        // スクロール帯の正準表現 (修理して非空へ戻すと最終凍結列が両帯へ重複する — R1 実証)。
+        // effectiveFrozenCols > 0 は colCount > 0 を含意する (min クランプ) ため条件は 1 項
+        if (effectiveFrozenCols > 0) {
+            placement.renderingColStart = Math.max(placement.renderingColStart, effectiveFrozenCols)
+            placement.visibleColStart = Math.max(placement.visibleColStart, effectiveFrozenCols)
+        }
+        // 末尾帯の ceiling clamp (3.5.0 プラン §6.1-6 — F 床クランプの鏡像・anti-#4454):
+        // stale-bandWidth や幅 0 末尾列で窓末端が末尾帯へ届いても、スクロール窓に末尾列を
+        // 再出現させない。天井は colCount − T_eff − 1 そのもの
+        if (effectiveTrailingCols > 0) {
+            const ceiling = colCount - effectiveTrailingCols - 1
+            placement.renderingColEnd = Math.min(placement.renderingColEnd, ceiling)
+            placement.visibleColEnd = Math.min(placement.visibleColEnd, ceiling)
+        }
+        // 空窓ガードの一般化 (3.5.0 プラン §6.1-6): F > 0 または T > 0 のとき、縮退帯
+        // (帯幅 ≤ 0 — W_F + W_T ≥ viewport) と clamp の結果 start > end になった窓は
+        // 全列凍結と同じ空窓正準形へ整形する (非空の可視窓を報告するとヘッダー同期 /
+        // liveRegion 消費側がセル無き列を描く — R3 実証の非対称の解消。T のみ縮退の
+        // phantom 窓もここで封じる)
+        if ((effectiveFrozenCols > 0 || effectiveTrailingCols > 0) && (bandWidth <= 0 || placement.renderingColStart > placement.renderingColEnd)) {
+            placement.renderingColStart = colCount
+            placement.renderingColEnd = colCount - 1
+            placement.visibleColStart = colCount
+            placement.visibleColEnd = colCount - 1
+        }
+        const key = `${placement.renderingColStart}:${placement.renderingColEnd}:${placement.colAnchor}`
+        if (key !== columnWindowRef.current.key) {
+            setColumnWindow({ ...placement, key })
+        }
+    }, [overscanCols, colCount, validatedGetColWidth, colTree, effectiveFrozenCols, effectiveTrailingCols, scrollBandWidthRef])
+
+    // ---- 横スクロールバーの追従 (rAF 合流の軽量 state — React 毎フレーム再レンダー回避) ----
+    const [barHx, setBarHx] = useState(0)
+    const barFrameRef = useRef<number | null>(null)
+    const scheduleBarSync = useCallback(() => {
+        if (barFrameRef.current !== null) {
+            return
+        }
+        barFrameRef.current = requestAnimationFrame(() => {
+            barFrameRef.current = null
+            setBarHx(hxRef.current)
+        })
+    }, [])
+    useEffect(
+        () => () => {
+            if (barFrameRef.current !== null) {
+                cancelAnimationFrame(barFrameRef.current)
+            }
+        },
+        [],
+    )
+
+    // ---- onScroll / onRangeChange の合成通知 ----
+    const onScrollRef = useRef(onScroll)
+    onScrollRef.current = onScroll
+    const onRangeChangeRef = useRef(onRangeChange)
+    onRangeChangeRef.current = onRangeChange
+    const onRenderTruncatedRef = useRef(onRenderTruncated)
+    onRenderTruncatedRef.current = onRenderTruncated
+    const rowRangeRef = useRef<VirtualScrollRange | null>(null)
+    // 描画行数はセル上限の分母。実測通知 (state) は 1 コミット遅れるため、通知到着までは
+    // 同期見積り (具現化行ウォーク) を分母に使う — マウントコミットの上限突破 (分母 1) の根治
+    const [notifiedRowCount, setNotifiedRowCount] = useState<number | null>(null)
+    // ビューポート高が変わるコミットも通知が 1 コミット遅れる — 古い実測を render 中に即時無効化し、
+    // 同一コミットから新鮮な見積りへ切替える (derived-state パターン。リサイズ拡大時の上限突破の根治)
+    const [prevViewportHeight, setPrevViewportHeight] = useState(viewport.height)
+    if (prevViewportHeight !== viewport.height) {
+        setPrevViewportHeight(viewport.height)
+        setNotifiedRowCount(null)
+    }
+    const initialAnchorRow = initialScrollAnchor === undefined || rowCount === 0 ? 0 : minmax(Math.trunc(initialScrollAnchor.row), 0, rowCount - 1)
+    const estimatedRowCount = useMemo(() => {
+        // 見積り基点は現在の行窓先頭 (到達済みなら) — マウント前は初期アンカー行。
+        // リサイズ時に初期アンカー基点のままだと現在位置と別領域の行高で見積もってしまう
+        const basisRow = rowRangeRef.current?.renderingStartIndex ?? initialAnchorRow
+        // 凍結行帯 (先頭 + 末尾) はスクロール行の見積り高から控除する (帯外バンド — 設計 §4-3、
+        // 3.5.0 プラン §6.1-12: −H_T 欠落は高い末尾帯のマウントコミットで偽打切りを発火させる)
+        return estimateRenderedRowCount(Math.max(0, viewport.height - frozenHeightRef.current - trailingHeightRef.current), validatedGetRowHeight, rowCount, basisRow, overscanRows)
+    }, [viewport.height, validatedGetRowHeight, rowCount, initialAnchorRow, overscanRows, frozenHeightEpochKey, trailingHeightEpochKey])
+    const effectiveRenderedRows = notifiedRowCount ?? estimatedRowCount
+
+    const buildRange = useCallback((): VirtualGridRange | null => {
+        const rows = rowRangeRef.current
+        if (rows === null) {
+            return null
+        }
+        const cols = columnWindowRef.current
+        return {
+            renderingRowStart: rows.renderingStartIndex,
+            renderingRowEnd: rows.renderingEndIndex,
+            visibleRowStart: rows.visibleStartIndex,
+            visibleRowEnd: rows.visibleEndIndex,
+            renderingColStart: cols.renderingColStart,
+            renderingColEnd: cols.renderingColEnd,
+            visibleColStart: cols.visibleColStart,
+            visibleColEnd: cols.visibleColEnd,
+            scrollX: hxRef.current,
+            scrollY: vyRef.current,
+            totalWidth: totalWidthRef.current,
+            // 帯高は鮮度加算 (格納はスクロール木のみ — 帯行リサイズ後も総高が正しい。R1 是正。
+            // 3.5.0: 末尾帯高 H_T も同じ鮮度規律で加算)
+            totalHeight: rows.totalHeight + frozenHeightRef.current + trailingHeightRef.current,
+        }
+    }, [])
+
+    const emitRangeChange = useCallback(() => {
+        const range = buildRange()
+        if (range !== null) {
+            onRangeChangeRef.current?.(range)
+        }
+    }, [buildRange])
+
+    // ---- applyHx — 横論理位置の唯一の書き口 (clamp → ref → 残差 var → 列窓 → 通知 → クランプ後値 return) ----
+    const applyHx = useCallback(
+        (next: number): number => {
+            // 凍結帯 (§8): スクロール帯幅 = viewport − W_F − W_T (3.5.0 一般化)。maxHx =
+            // (総幅 − W_F − W_T) − 帯幅で、W_F + W_T < viewport のとき従来式 (総幅 − viewport)
+            // と一致する (F = T = 0 で恒等)
+            const bandWidth = scrollBandWidthRef()
+            const maxHx = Math.max(0, totalWidthRef.current - frozenWidthRef.current - trailingWidthRef.current - bandWidth)
+            const clamped = minmax(next, 0, maxHx)
+            if (clamped !== hxRef.current) {
+                hxRef.current = clamped
+                writeResidual()
+                refreshColumns()
+                scheduleBarSync()
+                onScrollRef.current?.({ x: clamped, y: vyRef.current })
+            }
+            return clamped
+        },
+        [writeResidual, refreshColumns, scheduleBarSync, scrollBandWidthRef],
+    )
+    const applyHxRef = useRef(applyHx)
+    applyHxRef.current = applyHx
+
+    // ---- コミット後のアンカー公開 + 残差再書き (M10: セル left とペアで paint 前に切替) ----
+    useLayoutEffect(() => {
+        committedAnchorRef.current = columnWindow.colAnchor
+        writeResidual()
+        emitRangeChange()
+    }, [columnWindow, writeResidual, emitRangeChange])
+
+    // ---- 帯高変化の再通知 (R1 是正): 帯行リサイズは埋め込み側の onRangeChange を発火させない
+    //      (帯は木の外) — buildRange の鮮度加算と対で、消費側とライブリージョンへ明示再配送する ----
+    useLayoutEffect(() => {
+        if (rowRangeRef.current !== null) {
+            emitRangeChange()
+        }
+    }, [frozenHeight, trailingHeight, emitRangeChange])
+
+    // ---- 保留列アンカー (行側 scrollToIndex のアンカー張りの列対): initialScrollAnchor 復元と
+    //      scrollToCell が張り、self-heal / 総幅同期 / リサイズで列左が動くたび paint 前に再ピン留め
+    //      する (推定空間 → 実測空間の遷移をアンカーが生き延びる = M5)。手動横入力で解除 ----
+    const pendingColAnchorRef = useRef<{ col: number; alignX: "start" | "end" | "center"; offsetX: number } | null>(null)
+    /** Resolves the pending column anchor to an hx in the CURRENT tree space. / 保留列アンカーを現在の木空間の hx へ解決。 */
+    const resolveColumnAnchorHx = useCallback(
+        (anchor: { col: number; alignX: "start" | "end" | "center"; offsetX: number }): number => {
+            // colCount 縮小で範囲外化したアンカーは最終列へ明示クランプ (fail-safe — 木側の暗黙
+            // クランプへ依存しない。挙動は §7 の既知の制約として記録)
+            const safeCol = minmax(anchor.col, 0, Math.max(0, colCount - 1))
+            const prefix = colTree.prefixSum(safeCol, { materializeOption: { materialize: false } })
+            const colLeft = prefix.cumulative - prefix.currentValue
+            const colWidth = prefix.currentValue
+            // 凍結帯 (§8): 整列先はスクロール帯 [W_F, viewport − W_T) — 列座標から W_F を引き、
+            // 幅もスクロール帯幅 (3.5.0 一般化: −W_T 済み) で測る (F = T = 0 では従来式と恒等。
+            // "end" は目標右端を viewport − W_T へ着地させる — §8 の VALUE 行がピンする形)
+            const bandWidth = scrollBandWidthRef()
+            const base = anchor.alignX === "end" ? colLeft + colWidth - frozenWidthRef.current - bandWidth : anchor.alignX === "center" ? colLeft + colWidth / 2 - frozenWidthRef.current - bandWidth / 2 : colLeft - frozenWidthRef.current
+            return base + anchor.offsetX
+        },
+        [colTree, colCount, scrollBandWidthRef],
+    )
+
+    // ---- 幅 self-heal (窓内の getColWidth と木の乖離をバッチ適用 — 行 memo の toUpdateHeights 双子)。
+    //      適用後はエポックを繰上げ、治癒前の stale な左座標で確定したセル配置を再計算させる ----
+    const pendingWidthUpdatesRef = useRef<Array<{ index: number; value: number }> | null>(null)
+    const flushWidthUpdates = useCallback(() => {
+        const updates = pendingWidthUpdatesRef.current
+        pendingWidthUpdatesRef.current = null
+        if (updates === null || updates.length === 0) {
+            return
+        }
+        commitTotalWidth(colTree.updates(updates))
+        setWidthEpoch((epoch) => epoch + 1)
+    }, [colTree, commitTotalWidth])
+
+    // ---- 凍結帯の列挙 (設計 §8 — 窓化されない静的帯)。幅 self-heal は共有バッチへ合流し、
+    //      暴走ガードは帯専用カウンタ (スクロール窓側と独立 — 凍結専用振動アクセサが窓側の
+    //      収束リセットで永久にガードを回避する穴を作らない) ----
+    const frozenHealBurstRef = useRef({ count: 0, warned: false })
+    const { frozenColumns, frozenWidth } = useMemo(() => {
+        // widthEpoch は木内容バージョンの反応辺 (スクロール窓 memo と同じ規律)
+        void widthEpoch
+        if (effectiveFrozenCols === 0) {
+            // 凍結解除は帯ガードのエピソードも閉じる — 次の凍結エピソードが停止状態を継承して
+            // 無言で self-heal 不能になる越境リークの遮断 (R3 実証)
+            frozenHealBurstRef.current.count = 0
+            frozenHealBurstRef.current.warned = false
+            return { frozenColumns: EMPTY_PLACED_COLUMNS, frozenWidth: 0 }
+        }
+        const { columns, widthUpdates, width } = collectFrozenColumns(effectiveFrozenCols, validatedGetColWidth, colTree)
+        if (widthUpdates.length > 0) {
+            const burst = frozenHealBurstRef.current
+            if (burst.count >= WIDTH_HEAL_BURST_LIMIT) {
+                if (!burst.warned) {
+                    burst.warned = true
+                    Logger.warn("[VirtualGrid] getColWidth keeps disagreeing with its own previous values inside the frozen band; width self-heal is suspended until a converged pass re-arms it (unstable accessor).", {
+                        frozenCols: effectiveFrozenCols,
+                        pendingUpdates: widthUpdates.length,
+                    })
+                }
+            } else {
+                burst.count += 1
+                // スクロール窓側と同じ共有バッチへ合流 (append — 同 tick の両者の治癒を 1 フラッシュに)
+                pendingWidthUpdatesRef.current = [...(pendingWidthUpdatesRef.current ?? []), ...widthUpdates]
+                Promise.resolve().then(flushWidthUpdates)
+            }
+        } else {
+            frozenHealBurstRef.current.count = 0
+            frozenHealBurstRef.current.warned = false
+        }
+        return { frozenColumns: columns, frozenWidth: width }
+    }, [effectiveFrozenCols, widthEpoch, validatedGetColWidth, colTree, flushWidthUpdates])
+    frozenWidthRef.current = frozenWidth
+    // 凍結幅 var の書き手 (1 点): クリップ左端 (.aqvs-grid-row-scroll の left) と残差の −W_F 項
+    // (.aqvs-grid-row-scroll-inner の calc) の両消費者が読む
+    useLayoutEffect(() => {
+        // F = 0 は DOM 構造 (インライン属性まで) 従来と恒等に保つ — var は凍結モードのみ書き、
+        // 解除時は除去する (CSS 側は 0px フォールバックを持つため除去で安全)
+        if (effectiveFrozenCols > 0) {
+            rootRef.current?.style.setProperty("--aqvs-grid-frozen-width", `${frozenWidth}px`)
+        } else {
+            rootRef.current?.style.removeProperty("--aqvs-grid-frozen-width")
+        }
+    }, [frozenWidth, effectiveFrozenCols])
+
+    // ---- 末尾列帯の列挙 (3.5.0 プラン §6.1-7 — 先頭帯 memo の接尾辞双子)。self-heal 差分は
+    //      共有バッチへ append 合流し、暴走ガードは帯専用の独立カウンタ (T = 0 でエピソードを
+    //      閉じる — 先頭帯の「越境リーク遮断」と同文) ----
+    const trailingHealBurstRef = useRef({ count: 0, warned: false })
+    const { trailingColumns, trailingWidth } = useMemo(() => {
+        // widthEpoch は木内容バージョンの反応辺 (先頭帯 memo と同じ規律)
+        void widthEpoch
+        if (effectiveTrailingCols === 0) {
+            // 末尾凍結解除は帯ガードのエピソードも閉じる (先頭帯の R3 実証と同文の遮断)
+            trailingHealBurstRef.current.count = 0
+            trailingHealBurstRef.current.warned = false
+            return { trailingColumns: EMPTY_PLACED_COLUMNS, trailingWidth: 0 }
+        }
+        const { columns, widthUpdates, width } = collectTrailingColumns(colCount, effectiveTrailingCols, validatedGetColWidth, colTree)
+        if (widthUpdates.length > 0) {
+            const burst = trailingHealBurstRef.current
+            if (burst.count >= WIDTH_HEAL_BURST_LIMIT) {
+                if (!burst.warned) {
+                    burst.warned = true
+                    Logger.warn("[VirtualGrid] getColWidth keeps disagreeing with its own previous values inside the trailing band; width self-heal is suspended until a converged pass re-arms it (unstable accessor).", {
+                        trailingCols: effectiveTrailingCols,
+                        pendingUpdates: widthUpdates.length,
+                    })
+                }
+            } else {
+                burst.count += 1
+                // 共有バッチへ append 合流 (同 tick の先頭帯 / スクロール窓の治癒を上書きで落とさない)
+                pendingWidthUpdatesRef.current = [...(pendingWidthUpdatesRef.current ?? []), ...widthUpdates]
+                Promise.resolve().then(flushWidthUpdates)
+            }
+        } else {
+            trailingHealBurstRef.current.count = 0
+            trailingHealBurstRef.current.warned = false
+        }
+        return { trailingColumns: columns, trailingWidth: width }
+    }, [effectiveTrailingCols, colCount, widthEpoch, validatedGetColWidth, colTree, flushWidthUpdates])
+    trailingWidthRef.current = trailingWidth
+    // 末尾幅 var の書き手 (3.5.0 プラン §6.1-8 — **単一書き手規律**: この effect だけが書く)。
+    // 消費者はクリップ右端 (.aqvs-grid-row-scroll の right)・末尾クリップの max() 左端と inner 幅。
+    // T = 0 は除去 (T = 0 恒等 — CSS 側 0px フォールバックで安全)
+    useLayoutEffect(() => {
+        if (effectiveTrailingCols > 0) {
+            rootRef.current?.style.setProperty("--aqvs-grid-trailing-width", `${trailingWidth}px`)
+        } else {
+            rootRef.current?.style.removeProperty("--aqvs-grid-trailing-width")
+        }
+    }, [trailingWidth, effectiveTrailingCols])
+
+    // ---- ビューポート / 総幅 / 幅エポック変化での再クランプ + 列窓追随。保留列アンカーが
+    //      あれば位置はアンカーから再導出 (単なる再クランプでは推定空間の hx が残留する) ----
+    useLayoutEffect(() => {
+        const pending = pendingColAnchorRef.current
+        if (pending === null) {
+            applyHxRef.current(hxRef.current)
+        } else {
+            applyHxRef.current(resolveColumnAnchorHx(pending))
+        }
+        refreshColumns()
+    }, [viewport.width, totalWidth, widthEpoch, frozenWidth, trailingWidth, refreshColumns, resolveColumnAnchorHx])
+
+    // ---- 初期アンカー復元 (横) — 生 px でなく {col, offsetX} (行と同一契約)。マウント時 1 回。
+    //      保留列アンカーとして張り、以後の self-heal による列左の実測化へ追随させる ----
+    const initialAnchorAppliedRef = useRef(false)
+    useLayoutEffect(() => {
+        if (initialAnchorAppliedRef.current || initialScrollAnchor === undefined || colCount === 0) {
+            return
+        }
+        initialAnchorAppliedRef.current = true
+        const targetCol = minmax(Math.trunc(initialScrollAnchor.col), 0, colCount - 1)
+        // 凍結列狙いの x 復元は no-op (§8 — 常時可視のため hx 0 のままが復元そのもの)
+        if (targetCol < effectiveFrozenCols) {
+            return
+        }
+        // 末尾凍結列狙いも同文の no-op (3.5.0 プラン §6.1-16 — appliedRef を先に立てる現行順序は
+        // 仕様 §7 の登記済み未検証防御と同じ姿勢で維持)
+        if (targetCol >= colCount - effectiveTrailingCols) {
+            return
+        }
+        const anchor = { col: targetCol, alignX: "start" as const, offsetX: Math.max(0, initialScrollAnchor.offsetX) }
+        pendingColAnchorRef.current = anchor
+        applyHxRef.current(resolveColumnAnchorHx(anchor))
+    }, [initialScrollAnchor, colCount, resolveColumnAnchorHx, effectiveFrozenCols, effectiveTrailingCols])
+
+    // ---- 縦軸の結線 ----
+    const handleVerticalScroll = useCallback((position: number) => {
+        vyRef.current = position
+        attachedRef.current = true
+        onScrollRef.current?.({ x: hxRef.current, y: position })
+    }, [])
+    const handleVerticalRangeChange = useCallback(
+        (range: VirtualScrollRange) => {
+            // 行凍結 (設計 §3): 埋め込み VirtualScroll はシフト空間 (行 − R) で通知する — フル
+            // 行空間へ +R 翻訳して保持する (翻訳シームはここ 1 点)。スクロール行ゼロ (全行凍結 /
+            // rowCount ≤ R) と縮退帯 (H_F ≥ ビューポート — R1 是正で列 §3.3 と対称化) は正準空窓
+            // start > end。totalHeight は**スクロール木のみ**を格納し、帯高は buildRange が毎回
+            // 鮮度加算する (帯行リサイズが通知済みレンジを陳腐化させない — R1 是正)
+            if (scrollRowCount === 0 || degenerateBandRef.current) {
+                rowRangeRef.current = { renderingStartIndex: rowCount, renderingEndIndex: rowCount - 1, visibleStartIndex: rowCount, visibleEndIndex: rowCount - 1, scrollPosition: 0, totalHeight: scrollRowCount === 0 ? 0 : range.totalHeight }
+                vyRef.current = 0
+            } else {
+                const shift = effectiveFrozenRows
+                rowRangeRef.current = {
+                    renderingStartIndex: range.renderingStartIndex + shift,
+                    renderingEndIndex: range.renderingEndIndex + shift,
+                    visibleStartIndex: range.visibleStartIndex + shift,
+                    visibleEndIndex: range.visibleEndIndex + shift,
+                    scrollPosition: range.scrollPosition,
+                    totalHeight: range.totalHeight,
+                }
+                vyRef.current = range.scrollPosition
+            }
+            setNotifiedRowCount((prev) => {
+                const next = Math.max(1, range.renderingEndIndex - range.renderingStartIndex + 1)
+                return next === prev ? prev : next
+            })
+            emitRangeChange()
+        },
+        [emitRangeChange, effectiveFrozenRows, scrollRowCount, rowCount],
+    )
+    const consumeHorizontalDelta = useCallback((deltaX: number) => {
+        // 手動横入力はアンカー張りを解除する (行側の「手動スクロールでアンカー解除」と同契約)
+        pendingColAnchorRef.current = null
+        // 相対 float 加算のみ (絶対 floor 経路は 1px 未満消失の行側反証に従い禁止)
+        applyHxRef.current(hxRef.current + deltaX)
+    }, [])
+
+    // ---- 描画列の列挙 (配置ごとに 1 回 — 行間で共有) + セル数上限 ----
+    // 凍結行帯 (先頭 + 末尾) は全帯行 × 全描画列を具現化する — 予算分母に帯行数を算入
+    // (行凍結設計 §4-7、3.5.0 プラン §6.1-13)
+    const maxColsPerRow = resolveMaxColsPerRow(__maxRenderedCells, effectiveRenderedRows + frozenRows.length + trailingRows.length)
+    // self-heal の暴走ガード: 乖離→治癒→再乖離の非収束が連続する = getColWidth が自身の
+    // 過去値と不一致を繰り返す契約違反 (振動アクセサ)。放置すると治癒→エポック→再走査の
+    // マイクロタスクループが無限旋回するため、上限で治癒を停止し 1 回だけ警告する。
+    // 状態は {count, warned} のみ — 窓キーは保持しない (キー基準の解消は窓端を動かす振動に
+    // 永久回避されるため構造的に持たない。解消は収束パスのみ)
+    const healBurstRef = useRef({ count: 0, warned: false })
+    const { placedColumns, truncatedCols } = useMemo(() => {
+        // widthEpoch は木の内容バージョンの反応辺 (木は identity 安定のため値経由では失効しない)
+        void widthEpoch
+        // 凍結帯 (§8): スクロール帯幅 ≤ 0 (W_F + W_T ≥ viewport の縮退 — 3.5.0 一般化) は
+        // スクロール列を描かない — 凍結帯 / 末尾帯自体は独立 memo が描き続ける定義済み縮退
+        const bandWidth = Math.max(0, viewport.width - frozenWidth - trailingWidth)
+        if (colCount === 0 || bandWidth <= 0) {
+            return { placedColumns: [] as PlacedColumn[], truncatedCols: 0 }
+        }
+        // 空窓 (start > end — 全列凍結の正準表現) は minmax クランプが潰す前に早期脱出する
+        if (columnWindow.renderingColStart > columnWindow.renderingColEnd) {
+            return { placedColumns: [] as PlacedColumn[], truncatedCols: 0 }
+        }
+        // セル予算は凍結列 + 末尾列ぶんを控除 (両帯セルも行ごとに具現化するため — 上限は行の総セル数)
+        const scrollColsBudget = Math.max(1, maxColsPerRow - frozenColumns.length - trailingColumns.length)
+        const { columns, widthUpdates, truncated } = collectVisibleColumns(minmax(columnWindow.renderingColStart, 0, colCount - 1), minmax(columnWindow.renderingColEnd, 0, colCount - 1), validatedGetColWidth, colTree, scrollColsBudget)
+        if (widthUpdates.length > 0) {
+            const burst = healBurstRef.current
+            if (burst.count >= WIDTH_HEAL_BURST_LIMIT) {
+                if (!burst.warned) {
+                    burst.warned = true
+                    Logger.warn("[VirtualGrid] getColWidth keeps disagreeing with its own previous values; width self-heal is suspended until a converged (zero-deviation) pass re-arms it (unstable accessor — the accessor must be index-stable while the ordering is unchanged).", {
+                        window: columnWindow.key,
+                        pendingUpdates: widthUpdates.length,
+                    })
+                }
+            } else {
+                burst.count += 1
+                // render 中の木変異を避け、マイクロタスクでバッチ適用 (行 memo と同じ遅延照合)。
+                // append 合流 — 同一レンダーパスで先行する凍結 memo の治癒を上書きで落とさない
+                pendingWidthUpdatesRef.current = [...(pendingWidthUpdatesRef.current ?? []), ...widthUpdates]
+                Promise.resolve().then(flushWidthUpdates)
+            }
+        } else {
+            // 収束パス (乖離ゼロ) はどの窓でもバーストを解消する — カウンタが測るのは
+            // 「連続する非収束」であり、逐次の正当な治癒 (毎回 1 フラッシュで収束) を振動と誤認
+            // してはならない。真の振動アクセサは収束パスを一度も作れないため停止を免れず、
+            // 停止後も健全な窓へ移れば収束パスで解消され、stale な窓へ戻ったときに治癒が再開する
+            healBurstRef.current.count = 0
+            healBurstRef.current.warned = false
+        }
+        return { placedColumns: columns, truncatedCols: truncated }
+        // deps へ trailingWidth / trailingColumns.length を明示追加 (3.5.0 プラン §6.1-6 / F4):
+        // bandWidth 式とスクロール列予算が同 memo 内で両値を読む — 追加を怠ると列窓キー不変の
+        // T トグルで memo が stale 化し、予算が trailing 分だけ過大に残る
+    }, [columnWindow, colCount, viewport.width, frozenWidth, trailingWidth, frozenColumns.length, trailingColumns.length, widthEpoch, validatedGetColWidth, colTree, maxColsPerRow, flushWidthUpdates])
+
+    // 打切りは無言にしない (設計 §3.2 — 行側の病的ガードと違い正当構成で到達し得る)
+    const lastTruncationKeyRef = useRef("")
+    useEffect(() => {
+        if (truncatedCols > 0) {
+            const key = `${columnWindow.key}:${truncatedCols}`
+            if (key !== lastTruncationKeyRef.current) {
+                lastTruncationKeyRef.current = key
+                // 打切り分子は両帯セル / 両帯行込みの exactness を維持する (3.5.0 プラン §6.1-13)
+                onRenderTruncatedRef.current?.({ renderedCells: (placedColumns.length + frozenColumns.length + trailingColumns.length) * (effectiveRenderedRows + frozenRows.length + trailingRows.length), droppedCols: truncatedCols })
+            }
+        }
+    }, [truncatedCols, columnWindow.key, placedColumns.length, frozenColumns.length, trailingColumns.length, effectiveRenderedRows, frozenRows.length, trailingRows.length])
+
+    // ---- 行レンダラー (VirtualScroll children) — セル left は「絶対 − コミット対象アンカー」 ----
+    const colAnchor = columnWindow.colAnchor
+    const renderRow = useCallback(
+        (rowIndex: number): ReactNode => {
+            const rowProps = getRowProps?.(rowIndex)
+            // 高さ 0 (非表示) 行はセル DOM を生成しない — 幅 0 列スキップの行双子。0 高でも
+            // セルを置くと消費側のセル装飾 (罫線等) が 1px 級のアーティファクトとして残り、
+            // 巨大な非表示ランでセル予算も浪費する (getRowHeight は検証済みアクセサで整数契約)
+            const hidden = validatedGetRowHeight(rowIndex) === 0
+            const scrollCells = hidden
+                ? null
+                : placedColumns.map(({ col, left, width }) => {
+                      const cellProps = getCellProps?.(rowIndex, col)
+                      const style: CSSProperties = { ...cellProps?.style, left: left - colAnchor, width }
+                      return (
+                          <div {...cellProps} key={getCellKey ? getCellKey(rowIndex, col) : col} className={twMerge("aqvs-grid-cell", cellProps?.className)} style={style}>
+                              {children(getCell(rowIndex, col), rowIndex, col)}
+                          </div>
+                      )
+                  })
+            // 横帯なし (既定) は従来 DOM と恒等 — 行が残差 translate を運ぶ (中身はバイト恒等)
+            if (effectiveFrozenCols === 0 && effectiveTrailingCols === 0) {
+                return (
+                    <div {...rowProps} className={twMerge("aqvs-grid-row", rowProps?.className)} style={rowProps?.style}>
+                        {scrollCells}
+                    </div>
+                )
+            }
+            // 横帯モード (§8-c + 3.5.0 プラン §6.1-15): 行は静的化し、スクロールセルは左端 W_F ・
+            // 右端 W_T の静的クリップ + −W_F 原点シフト付き残差 translate の内側へ。凍結セルは
+            // 行直下の独立 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}>
+                    {hidden
+                        ? null
+                        : frozenColumns.map(({ col, left, width }) => {
+                              const cellProps = getCellProps?.(rowIndex, col)
+                              const style: CSSProperties = { ...cellProps?.style, left, width }
+                              return (
+                                  <div {...cellProps} data-aqvs-frozen-cell="" key={getCellKey ? getCellKey(rowIndex, col) : col} className={twMerge("aqvs-grid-cell", cellProps?.className)} style={style}>
+                                      {children(getCell(rowIndex, col), rowIndex, col)}
+                                  </div>
+                              )
+                          })}
+                    {hidden ? null : (
+                        <div className="aqvs-grid-row-scroll">
+                            <div className="aqvs-grid-row-scroll-inner">{scrollCells}</div>
+                        </div>
+                    )}
+                    {hidden || effectiveTrailingCols === 0 ? null : (
+                        <div className="aqvs-grid-row-trailing">
+                            <div className="aqvs-grid-row-trailing-inner">
+                                {trailingColumns.map(({ col, left, width }) => {
+                                    const cellProps = getCellProps?.(rowIndex, col)
+                                    const style: CSSProperties = { ...cellProps?.style, left, width }
+                                    return (
+                                        <div {...cellProps} data-aqvs-trailing-cell="" key={getCellKey ? getCellKey(rowIndex, col) : col} className={twMerge("aqvs-grid-cell", cellProps?.className)} style={style}>
+                                            {children(getCell(rowIndex, col), rowIndex, col)}
+                                        </div>
+                                    )
+                                })}
+                            </div>
+                        </div>
+                    )}
+                </div>
+            )
+        },
+        [placedColumns, frozenColumns, trailingColumns, effectiveFrozenCols, effectiveTrailingCols, colAnchor, getRowProps, getCellProps, getCellKey, getCell, children, validatedGetRowHeight],
+    )
+
+    // ---- liveRegion (2D — 文言は消費側所有、静定デバウンス) ----
+    const [liveMessage, setLiveMessage] = useState("")
+    const liveTimerRef = useRef<number | null>(null)
+    const liveRegionRef = useRef(liveRegion)
+    liveRegionRef.current = liveRegion
+    const scheduleLiveMessage = useCallback(() => {
+        const options = liveRegionRef.current
+        if (options === undefined) {
+            return
+        }
+        // 不正な debounceMs は黙って既定へ読み替えず読み上げを無効化する (警告は下の effect が 1 回だけ出す)
+        const debounce = options.debounceMs ?? 400
+        if (!(Number.isFinite(debounce) && debounce >= 0)) {
+            return
+        }
+        if (liveTimerRef.current !== null) {
+            window.clearTimeout(liveTimerRef.current)
+        }
+        liveTimerRef.current = window.setTimeout(() => {
+            liveTimerRef.current = null
+            const range = buildRange()
+            if (range !== null) {
+                setLiveMessage((prev) => {
+                    const next = options.buildMessage(range)
+                    return next === prev ? prev : next
+                })
+            }
+        }, debounce)
+    }, [buildRange])
+    const liveDebounceMs = liveRegion?.debounceMs ?? 400
+    const liveDebounceValid = Number.isFinite(liveDebounceMs) && liveDebounceMs >= 0
+    const hasLiveRegion = liveRegion !== undefined
+    useEffect(() => {
+        // 目的: 不正な debounceMs の無効化を黙らせない (行側 liveRegion と同一契約の 1 回警告)
+        if (hasLiveRegion && !liveDebounceValid) {
+            Logger.warn(`[VirtualGrid] liveRegion.debounceMs must be a finite number >= 0, received ${liveDebounceMs}. Announcements are disabled.`)
+        }
+    }, [hasLiveRegion, liveDebounceValid, liveDebounceMs])
+    useEffect(
+        () => () => {
+            if (liveTimerRef.current !== null) {
+                window.clearTimeout(liveTimerRef.current)
+            }
+        },
+        [],
+    )
+    useEffect(() => {
+        scheduleLiveMessage()
+    }, [columnWindow, scheduleLiveMessage])
+    const handleRangeChangeWithLive = useCallback(
+        (range: VirtualScrollRange) => {
+            handleVerticalRangeChange(range)
+            scheduleLiveMessage()
+        },
+        [handleVerticalRangeChange, scheduleLiveMessage],
+    )
+
+    // ---- ハンドル ----
+    useImperativeHandle(
+        ref,
+        (): VirtualGridHandle => ({
+            scrollTo: (pos) => {
+                const inner = scrollHandleRef.current
+                let y = vyRef.current
+                if (pos.y !== undefined && inner !== null) {
+                    inner.scrollTo(pos.y)
+                    y = inner.getScrollPosition()
+                    vyRef.current = y
+                }
+                let x = hxRef.current
+                if (pos.x !== undefined) {
+                    // 明示ジャンプは列アンカーを張らない (設計 §3.4) — 既存の張りも解除する
+                    pendingColAnchorRef.current = null
+                    x = applyHxRef.current(pos.x)
+                }
+                return { x, y }
+            },
+            scrollBy: (delta) => {
+                const inner = scrollHandleRef.current
+                let y = vyRef.current
+                if (delta.y !== undefined && delta.y !== 0 && inner !== null) {
+                    y = inner.scrollBy(delta.y)
+                    vyRef.current = y
+                }
+                let x = hxRef.current
+                if (delta.x !== undefined && delta.x !== 0) {
+                    pendingColAnchorRef.current = null
+                    x = applyHxRef.current(hxRef.current + delta.x)
+                }
+                return { x, y }
+            },
+            scrollToCell: (row, col, options) => {
+                const inner = scrollHandleRef.current
+                if (inner !== null && rowCount > 0) {
+                    const targetRow = minmax(Math.trunc(row), 0, rowCount - 1)
+                    // 凍結行狙いの y は no-op (行凍結設計 §3 — 常時可視。列の §8 no-op と同文)。
+                    // 末尾帯行狙いも同文の縦 no-op (帯所属は**呼出し時**判定 — 3.5.0 プラン §3)。
+                    // スクロール行はシフト空間へ −R 翻訳して委譲する
+                    if (targetRow >= effectiveFrozenRows && targetRow < rowCount - effectiveTrailingRows) {
+                        inner.scrollToIndex(targetRow - effectiveFrozenRows, { align: options?.alignY ?? "top", offset: options?.offsetY })
+                    }
+                }
+                if (colCount > 0) {
+                    const targetCol = minmax(Math.trunc(col), 0, colCount - 1)
+                    // 凍結列狙いの x は no-op (§8 — 常時可視)。末尾列狙いも横 no-op かつ既存の
+                    // 列アンカー残置 (分岐スキップのみ — pendingColAnchorRef は触らない。3.5.0 §3)
+                    if (targetCol >= effectiveFrozenCols && targetCol < colCount - effectiveTrailingCols) {
+                        // 列アンカーを張る (行 scrollToIndex のアンカー張りと同義): 以後の self-heal で
+                        // 列左が実測化されても狙った列に留まり続ける。手動横入力で解除
+                        const anchor = { col: targetCol, alignX: options?.alignX ?? "start", offsetX: options?.offsetX ?? 0 }
+                        pendingColAnchorRef.current = anchor
+                        applyHxRef.current(resolveColumnAnchorHx(anchor))
+                    }
+                }
+            },
+            getScrollPosition: () => (attachedRef.current || scrollHandleRef.current !== null ? { x: hxRef.current, y: scrollHandleRef.current?.getScrollPosition() ?? vyRef.current } : { x: -1, y: -1 }),
+            getScrollAnchor: () => {
+                if (rowCount === 0 || colCount === 0) {
+                    return null
+                }
+                const rowAnchor = scrollHandleRef.current?.getScrollAnchor() ?? null
+                if (rowAnchor === null) {
+                    return null
+                }
+                // 境界規約は行側 getScrollAnchor と同一: 末尾越えは最終列 offsetX 0、列の右端が
+                // ちょうど hx (cumulative === hx) なら可視先頭は次列 offsetX 0 — {index, offset}
+                // 分解が列幅変更を跨いでも行側と同じ列に解決される (M5 のアンカー不変性)
+                // 凍結帯 (§8): アンカーはスクロール帯の可視先頭 = 木座標 W_F + hx で捕獲する
+                // (復元側 resolveColumnAnchorHx が W_F を引き戻すため往復が恒等)
+                const bandStart = frozenWidthRef.current + hxRef.current
+                const found = colTree.findIndexAtOrAfter(bandStart, { materializeOption: { materialize: false } })
+                if (found.index === -1) {
+                    return { row: rowAnchor.index + effectiveFrozenRows, col: colCount - 1, offsetX: 0, offsetY: rowAnchor.offsetPx }
+                }
+                if (found.cumulative === bandStart) {
+                    return { row: rowAnchor.index + effectiveFrozenRows, col: minmax(found.index + 1, 0, colCount - 1), offsetX: 0, offsetY: rowAnchor.offsetPx }
+                }
+                // 行はシフト空間 → フル行空間へ +R 翻訳 (行凍結設計 §3 — 復元側は −R で往復恒等)
+                const colLeft = (found.cumulative ?? 0) - (found.currentValue ?? 0)
+                return { row: rowAnchor.index + effectiveFrozenRows, col: found.index, offsetX: Math.max(0, bandStart - colLeft), offsetY: rowAnchor.offsetPx }
+            },
+            getViewportSize: () => ({ width: viewportRef.current.width, height: viewportRef.current.height }),
+            // 縦はインセット込みの行側 getContentSize を単一情報源にする (range.totalHeight は木総高のみ)。
+            // 3.5.0: height = H_F + 埋め込み + H_T
+            getContentSize: () => ({ width: totalWidthRef.current, height: scrollHandleRef.current === null ? 0 : frozenHeightRef.current + trailingHeightRef.current + Math.max(0, scrollHandleRef.current.getContentSize()) }),
+            getRange: buildRange,
+            updateRowSize: (row, px) => {
+                validateTrackSize(px, "row", row)
+                // 凍結行はグリッド所有バンド — epoch 繰上げでアクセサ再読 (帯に第 2 の格納庫は
+                // 無いため木更新は不要)。末尾帯行も同文の epoch 繰上げ (3.5.0 — 3 分岐。T = 0 は
+                // 分岐自体が不成立で従来挙動と恒等)。スクロール行はシフト空間へ −R 翻訳して委譲する
+                if (Math.trunc(row) < effectiveFrozenRows) {
+                    setFrozenRowEpoch((epoch) => epoch + 1)
+                } else if (effectiveTrailingRows > 0 && Math.trunc(row) >= rowCount - effectiveTrailingRows) {
+                    setTrailingRowEpoch((epoch) => epoch + 1)
+                } else {
+                    scrollHandleRef.current?.updateItemSize(Math.trunc(row) - effectiveFrozenRows, px)
+                }
+            },
+            updateColSize: (col, px) => {
+                validateTrackSize(px, "col", col)
+                // 総幅は ref へも即時反映 (同 tick の scrollBy/scrollTo が旧上限でクランプしないため)
+                commitTotalWidth(colTree.update(minmax(Math.trunc(col), 0, Math.max(0, colCount - 1)), px))
+                // 窓キー不変の幅変更でもセル配置を失効させる (バッチループは React 自動バッチングで 1 コミット)
+                setWidthEpoch((epoch) => epoch + 1)
+            },
+            getFrozenSize: () => ({
+                cols: effectiveFrozenCols,
+                width: frozenWidthRef.current,
+                rows: effectiveFrozenRows,
+                height: frozenHeightRef.current,
+                trailingCols: effectiveTrailingCols,
+                trailingRows: effectiveTrailingRows,
+                trailingWidth: trailingWidthRef.current,
+                trailingHeight: trailingHeightRef.current,
+                // vis は単一 JS 源ヘルパーの呼び出しのみ (式の再導出禁止 — 3.5.0 プラン §2.1-4)
+                trailingVisibleWidth: trailingVisibleSize(trailingWidthRef.current, frozenWidthRef.current, viewportRef.current.width),
+                trailingVisibleHeight: trailingVisibleSize(trailingHeightRef.current, frozenHeightRef.current, viewportRef.current.height),
+            }),
+            applyWheel: (event) => scrollHandleRef.current?.applyWheel(event) ?? false,
+            focusRowAtIndex: (row, options) => {
+                // 凍結行はバンド行 DOM へ直接フォーカス、末尾帯行も帯行 DOM へ直接フォーカス
+                // (3.5.0 — 3 分岐。T = 0 は分岐不成立で従来挙動と恒等)、スクロール行は −R 翻訳して委譲
+                const targetRow = Math.trunc(row)
+                if (targetRow < effectiveFrozenRows) {
+                    rootRef.current?.querySelector<HTMLElement>(`[data-aqvs-frozen-band-row="${targetRow}"]`)?.focus()
+                } else if (effectiveTrailingRows > 0 && targetRow >= rowCount - effectiveTrailingRows) {
+                    rootRef.current?.querySelector<HTMLElement>(`[data-aqvs-trailing-band-row="${targetRow}"]`)?.focus()
+                } else {
+                    scrollHandleRef.current?.focusItemAtIndex(targetRow - effectiveFrozenRows, options)
+                }
+            },
+        }),
+        [rowCount, colCount, colTree, buildRange, commitTotalWidth, resolveColumnAnchorHx, effectiveFrozenCols, effectiveFrozenRows, effectiveTrailingCols, effectiveTrailingRows],
+    )
+
+    return (
+        <div ref={rootRef} className={twMerge("aqvs-grid", effectiveFrozenRows > 0 ? "aqvs-grid-has-frozen-rows" : "", effectiveTrailingRows > 0 ? "aqvs-grid-has-trailing-rows" : "", className)} data-testid={testId}>
+            {effectiveFrozenRows > 0 ? (
+                // 凍結行帯 (行凍結設計 §4-2): グリッド所有の帯外バンド — 行本体は renderRow を
+                // そのまま再利用する (F > 0 の凍結セル / クリップ / hx 残差 var は継承で無償追随
+                // = 4 象限コーナーの成立点)。top は木絶対プレフィックス、高さ 0 行は DOM 非生成
+                <div className="aqvs-grid-frozen-rows" style={{ height: frozenHeight }} data-testid={testId ? `${testId}-frozen-rows` : undefined}>
+                    {frozenRows.map(({ row, top, height }) => (
+                        // 行ラッパーの role は消費側の複合ウィジェット契約 (listbox / tree / grid — README
+                        // 「Composite widget roles」) の所有物で、パッケージが既定 role を課すと衝突する。
+                        // フォーカス結線は focusRowAtIndex ↔ onRowFocus 往復のバンド版そのもの。右インセット
+                        // (right: scrollBarWidth + overflow クリップ) は縦バーコーナーの予約 — ペインの
+                        // クリップ箱 (root − バー幅) と帯のクリップ箱を一致させる (R1 是正)。
+                        // biome-ignore lint/a11y/noStaticElementInteractions: role は消費側の複合ウィジェット契約の所有物 (上記)
+                        <div key={row} data-aqvs-frozen-band-row={row} className="aqvs-grid-frozen-band-row" style={{ top, height, right: scrollBarWidth }} tabIndex={-1} onFocus={() => onRowFocus?.(row)}>
+                            {renderRow(row)}
+                        </div>
+                    ))}
+                </div>
+            ) : null}
+            <div className="aqvs-grid-main" data-testid={testId ? `${testId}-main` : undefined}>
+                <VirtualScroll<number>
+                    key={effectiveFrozenRows}
+                    ref={scrollHandleRef}
+                    itemCount={degenerateBand ? 0 : scrollRowCount}
+                    getItem={(i) => i + effectiveFrozenRows}
+                    getItemKey={(i) => i + effectiveFrozenRows}
+                    getItemHeight={scrollGetRowHeight}
+                    overscanCount={overscanRows}
+                    viewportSize={viewport.height > 0 ? Math.max(0, viewport.height - frozenHeight - trailingHeight) : undefined}
+                    callbackThrottleMs={callbackThrottleMs}
+                    behaviorOptions={behaviorOptions}
+                    scrollBarOptions={scrollBarOptions}
+                    contentProps={contentProps}
+                    background={background}
+                    contentInsets={contentInsets}
+                    onItemFocus={shiftedRowFocus}
+                    horizontalKeyInputs={horizontalKeyInputs}
+                    horizontalKeyStep={horizontalKeyStep}
+                    initialScrollAnchor={
+                        // トグル済みなら視点保存 (捕捉アンカー) のみ — 捕捉 null は undefined (先頭)
+                        // へ落とし、消費済みマウント props の蘇りを断つ (R2 是正)。未トグルのみ
+                        // マウント props の凍結行 no-op 付き −R 変換 (列の §8 no-op と同文)
+                        toggledRef.current
+                            ? toggleAnchorRef.current !== null && toggleAnchorRef.current.row >= effectiveFrozenRows && scrollRowCount > 0
+                                ? { index: toggleAnchorRef.current.row - effectiveFrozenRows, offsetPx: toggleAnchorRef.current.offsetPx }
+                                : undefined
+                            : initialScrollAnchor !== undefined && scrollRowCount > 0 && Math.trunc(initialScrollAnchor.row) >= effectiveFrozenRows && Math.trunc(initialScrollAnchor.row) < rowCount - effectiveTrailingRows
+                              ? { index: Math.trunc(initialScrollAnchor.row) - effectiveFrozenRows, offsetPx: initialScrollAnchor.offsetY }
+                              : undefined
+                    }
+                    onScroll={handleVerticalScroll}
+                    onRangeChange={handleRangeChangeWithLive}
+                    onWheelHorizontal={consumeHorizontalDelta}
+                    onPanHorizontal={consumeHorizontalDelta}
+                    testId={testId ? `${testId}-rows` : undefined}>
+                    {renderRow}
+                </VirtualScroll>
+            </div>
+            {effectiveTrailingRows > 0 ? (
+                // 末尾行帯 (3.5.0 プラン §6.1-17): .aqvs-grid-main の**後**・hbar の**前**の兄弟
+                // (AT には「最終行が最後」の DOM 順正しさ。縦バーは帯の上で自然に終端)。帯クリップ高は
+                // インライン H_T_vis (単一 JS 源 — 帯寸の CSS 変数は幅 2 つのみで高さ変数は導入しない)、
+                // inner はインライン木高 H_T の bottom 定着 — 帯上端 = extent − H_T_vis が全構成で
+                // 成立し、重複縮退では帯の**末尾**行が可視に残る。行本体は renderRow 逐語再利用
+                // (先頭列 / 末尾列の帯構造を継承し 4 象限コーナー全種が無償で成立)
+                <div className="aqvs-grid-trailing-rows" style={{ height: trailingVisibleSize(trailingHeight, frozenHeight, viewport.height) }} data-testid={testId ? `${testId}-trailing-rows` : undefined}>
+                    <div className="aqvs-grid-trailing-rows-inner" style={{ height: trailingHeight }}>
+                        {trailingRows.map(({ row, top, height }) => (
+                            // 帯行は帯ローカル top + right: scrollBarWidth (縦バーコーナーの予約 — 先頭帯行と
+                            // 同文) + tabIndex −1 + onFocus フル行 index (focusRowAtIndex ↔ onRowFocus 往復)。
+                            // biome-ignore lint/a11y/noStaticElementInteractions: role は消費側の複合ウィジェット契約の所有物 (先頭帯行と同文)
+                            <div key={row} data-aqvs-trailing-band-row={row} className="aqvs-grid-trailing-band-row" style={{ top, height, right: scrollBarWidth }} tabIndex={-1} onFocus={() => onRowFocus?.(row)}>
+                                {renderRow(row)}
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            ) : null}
+            <div className="aqvs-grid-hbar-strip" style={{ height: scrollBarWidth, paddingRight: effectiveTrailingCols > 0 ? scrollBarWidth + trailingVisibleSize(trailingWidth, frozenWidth, viewport.width) : scrollBarWidth }} data-testid={testId ? `${testId}-hbar` : undefined}>
+                <ScrollBar
+                    horizontal
+                    enableHorizontalTapCircle
+                    contentSize={Math.max(0, totalWidth - frozenWidth - trailingWidth)}
+                    viewportSize={Math.max(0, viewport.width - frozenWidth - trailingWidth)}
+                    scrollPosition={barHx}
+                    // タップ速度の log10(colCount) 則 (設計 §3.3 — B7 の対策そのもの)。未配線だと
+                    // 兆列でも基礎倍率 2.2x に縮退し、サム粒度の到達性が死ぬ。−F / −T 写像は
+                    // aria 面に露出せずピン不能 (仕様 §7 非ピン面 (3) の登記済み面)
+                    itemCount={Math.max(0, colCount - effectiveFrozenCols - effectiveTrailingCols)}
+                    tapScrollCircleOptions={scrollBarOptions?.tapScrollCircleOptions}
+                    onScroll={(request, previous) => {
+                        // バー操作は手動横入力 — 列アンカーの張りを解除する
+                        pendingColAnchorRef.current = null
+                        return applyHxRef.current(typeof request === "function" ? request(previous ?? hxRef.current) : request)
+                    }}
+                    scrollBarWidth={scrollBarWidth}
+                />
+            </div>
+            {liveRegion !== undefined ? (
+                <div className="aqvs-grid-live-region" aria-live="polite" data-testid={testId ? `${testId}-live` : undefined}>
+                    {liveMessage}
+                </div>
+            ) : null}
+        </div>
+    )
+}
+
+/**
+ * Generic 2D virtualization grid — see the fileoverview. Exposes VirtualGridHandle via ref.
+ * 汎用 2D 仮想化グリッド — fileoverview 参照。ref で VirtualGridHandle を公開する。
+ */
+export const VirtualGrid = forwardRef(VirtualGridInner) as <T>(props: VirtualGridProps<T> & { ref?: React.Ref<VirtualGridHandle> }) => ReactNode