@aiquants/spreadsheet 0.8.0

package/src/grid/CellView.tsx

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Single cell CONTENT leaf. Since v0.4 the positioned cell element itself is
+ * OWNED by VirtualGrid (left/width from the quantized column anchor; attributes from
+ * GridBody's getCellProps) — this component renders only what goes INSIDE it, memoized on
+ * primitives so an unchanged cell skips the renderCell execution during re-slices. Selection
+ * state NEVER flows here (ADR-4: selection is painted by the viewport-space overlay).
+ *
+ * セルの中身専用の葉コンポーネント。v0.4 から配置済みセル要素そのものは VirtualGrid の所有
+ * (left / width は量子化列アンカー由来、属性は GridBody の getCellProps) — 本コンポーネントは
+ * その**内側**だけを描画し、プリミティブ memo で不変セルの renderCell 再実行を再スライス時に
+ * スキップする。選択状態は流れない (ADR-4: 選択はビューポート空間オーバーレイが描く)。
+ */
+
+import { memo, type ProfilerOnRenderCallback, type ReactNode, useEffect, useRef } from "react"
+
+/** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
+export type RenderCellContext = { row: number; col: number; text: string }
+
+type CellViewProps = {
+    row: number
+    col: number
+    /** Canonical text the grid's getCell reads from adapter.getCellText (updated by re-slice). / グリッドの getCell が adapter.getCellText から読む正準文字列。 */
+    text: string
+    /** The public cell renderer (ADR-8); this is its execution point. / 公開レンダラーの実行点。 */
+    renderCell?: (ctx: RenderCellContext) => ReactNode
+    /** Test-only re-render counter injection point (§8.2); undefined in production. / テスト専用注入点。 */
+    __onCellRender?: ProfilerOnRenderCallback
+}
+
+/**
+ * Renders one cell's content (memo target — no own positioned element since v0.4).
+ * セル 1 枚の中身を描画 (memo 対象 — v0.4 から自前の配置要素は持たない)。
+ */
+const CellViewInner = ({ row, col, text, renderCell, __onCellRender }: CellViewProps): ReactNode => {
+    // テスト専用カウンタ: Profiler ノードの常設を避けるコスト取引 — 代わりに常設の passive
+    // effect 1 本が毎 commit 走る (注入なしなら本体は即 no-op)。フックは条件分岐できないため
+    // この登録コスト自体は受容する (初回 = mount、以後 = update)
+    const mountedRef = useRef(false)
+    useEffect(() => {
+        const phase = mountedRef.current ? "update" : "mount"
+        mountedRef.current = true
+        __onCellRender?.(`cell-${row}-${col}`, phase, 0, 0, 0, 0)
+    })
+    return renderCell ? renderCell({ row, col, text }) : text
+}
+
+/**
+ * Memo contract: props are primitives + renderCell (identity-stable per consumer contract).
+ * memo 契約: props はプリミティブ + renderCell (identity 安定が consumer 契約)。
+ */
+export const CellView = memo(CellViewInner)

package/src/grid/GridBody.tsx

@@ -0,0 +1,489 @@
+/**
+ * @fileoverview Grid body: owns the VirtualGrid wiring (both axes) and the cell renderer.
+ * Since v0.4 the horizontal axis is OWNED by VirtualGrid (quantized column anchor + residual
+ * transform + horizontal bar) — the v0.3 column stack (useColumnWindow / --aqsp-hx CSS variable
+ * / absolute axis-origin cell left / own HScrollBar) is deleted per §7-1 of the VirtualGrid
+ * design plan. Wrapped in React.memo — Spreadsheet shell re-renders (selection / edit session)
+ * are isolated by identity-stable props; edit repaints arrive from the INSIDE via the
+ * editVersion subscription (renderVersion delivery — §6.9-2).
+ *
+ * v0.8 rich cells (plan §4.2.11): `resolveRichCellProps` is the ONE place the adapter's rich-cell
+ * reads happen — at most eight per cell (painted format, right / below base formats for border
+ * ownership, note, comments, hyperlink, validation, and the lazily shared text) — and it paints
+ * them as inline style + `data-aqsp-*` state attributes. The display value format it resolved
+ * is latched per cell (`takeLatchedValue`) for the `children` renderer, which therefore reads
+ * nothing from the adapter — the engine's own `getCell` text read (v0.1) stays separate, so a
+ * mounted slice costs at most 3 format reads per cell. Every read is a capability branch
+ * (`adapter.x === undefined` ⇒ the v0.1 attribute-free cell), the conditional-format index is a
+ * declared capability of the root (absent ⇒ base format only), and unchanged cells keep
+ * identical style objects (two-tier intern: paint identity, then canonical JSON for the
+ * per-call paints of edge / folded cells).
+ *
+ * グリッド本体。VirtualGrid 結線 (両軸) とセルレンダラーを所有する。v0.4 から横軸は VirtualGrid
+ * の所有 (量子化列アンカー + 残差 transform + 横バー) — v0.3 の列スタック (useColumnWindow /
+ * --aqsp-hx CSS 変数 / 軸原点絶対 left / 自前 HScrollBar) は設計計画 §7-1 に従い削除。
+ * React.memo でラップし shell 再レンダーから隔離 — 編集反映は editVersion 購読で内側から届く
+ * (renderVersion 配送 — §6.9-2)。
+ *
+ * v0.8 リッチセル (計画 §4.2.11): `resolveRichCellProps` がアダプタのリッチセル読みを行う唯一の場所 —
+ * セル毎最大 8 読み (塗り書式・罫線所有のための右 / 下隣 base 書式・ノート・コメント・リンク・検証・
+ * 遅延共有の text) — で、インライン style + `data-aqsp-*` 状態属性として塗る。そこで解決した表示の
+ * 値書式はセル毎の掛け金 (`takeLatchedValue`) で `children` レンダラーへ渡すため children はアダプタを
+ * 一切読まない — エンジン自身の `getCell` text 読み (v0.1) は別で、マウント経路の書式読みはセル毎最大 3。
+ * 全読みは能力分岐 (`adapter.x === undefined` ⇒ v0.1 の属性なしセル)、条件付き書式索引は root の宣言能力 (未指定 ⇒
+ * base 書式のみ)、無変化セルは同一の style object を保つ (2 段 intern: paint identity → 端 / 畳込み
+ * セルの呼出毎 paint は正準 JSON)。
+ */
+
+import { VirtualGrid, type VirtualGridHandle, type VirtualGridRange } from "@aiquants/virtualscroll"
+import { type HTMLAttributes, memo, type ProfilerOnRenderCallback, type ReactNode, type RefObject, useCallback, useMemo, useRef, useSyncExternalStore } from "react"
+import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
+import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
+import { alignToJustify, type CellAlign, type CellValueFormat, formatCellValue } from "../model/cellFormat.ts"
+import { type CellPaint, resolveCellPaint } from "../model/cellPaint.ts"
+import { type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "../model/conditionalFormat.ts"
+import { lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { isVisiblyInvalid } from "../model/dataValidation.ts"
+import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
+import { CellView, type RenderCellContext } from "./CellView.tsx"
+
+/** Inline style of a cell (React camelCase keys). / セルのインライン style (React の camelCase キー)。 */
+type CellStyle = Readonly<Record<string, string>>
+
+/** Alignment-only styles for cells that paint nothing else — one shared frozen object per alignment. / 塗りなしセルの揃えだけの style — 揃え毎に共有の凍結 object 1 つ。 */
+const ALIGN_ONLY_STYLES: Readonly<Record<CellAlign, CellStyle>> = Object.freeze({
+    left: Object.freeze({ justifyContent: alignToJustify("left") }),
+    center: Object.freeze({ justifyContent: alignToJustify("center") }),
+    right: Object.freeze({ justifyContent: alignToJustify("right") }),
+})
+
+/** Whole-Map clearing threshold of the canonical-JSON style intern (the CF memo's bound). / 正準 JSON style intern の全消去しきい値 (CF memo と同じ上限)。 */
+export const STYLE_INTERN_LIMIT = 4096
+
+/** Tier 1: paint object → alignment → merged style (WeakMap so per-call paints never leak). / 第 1 段: paint object → 揃え → 合成 style (WeakMap なので呼出毎 paint はリークしない)。 */
+const styleByPaint = new WeakMap<CellPaint, Partial<Record<CellAlign, CellStyle>>>()
+
+/** Tier 2: canonical JSON of the merged style → the one frozen object (bounded). / 第 2 段: 合成 style の正準 JSON → 唯一の凍結 object (有界)。 */
+const styleByKey = new Map<string, CellStyle>()
+
+/**
+ * Interns the cell's inline style per (paint, resolved alignment): the paint's style plus the
+ * alignment's `justifyContent` (an explicit alignment in the paint carries the same value, so
+ * the merge never conflicts). Tier 1 keys by paint identity (interior cells — `resolveCellPaint`
+ * interns those per format object); tier 2 keys by the canonical JSON of the merged style so
+ * the per-call paints of edge / folded cells still resolve to ONE object. Same content ⇒ the
+ * SAME frozen object across re-slices, which is what lets React skip the style diff of
+ * unchanged cells. A null paint resolves to the shared alignment-only object. Barrel-private;
+ * exported for the pins.
+ * セルのインライン style を (paint, 解決済み揃え) で intern: paint の style + 揃えの `justifyContent`
+ * (paint 内の明示揃えは同じ値を運ぶため合成は衝突しない)。第 1 段は paint identity (内部セル —
+ * `resolveCellPaint` が書式 object 毎に intern 済み)、第 2 段は合成 style の正準 JSON で、端 / 畳込み
+ * セルの呼出毎 paint も 1 つの object へ解決する。同内容 ⇒ 再スライスを跨いで同一の凍結 object で、
+ * React が無変化セルの style diff を省ける根拠。paint null は共有の揃えだけの object。バレル非公開 —
+ * ピン用に export。
+ */
+export const internCellStyle = (paint: CellPaint | null, align: CellAlign): CellStyle => {
+    if (paint === null) {
+        return ALIGN_ONLY_STYLES[align]
+    }
+    let byAlign = styleByPaint.get(paint)
+    if (byAlign === undefined) {
+        byAlign = {}
+        styleByPaint.set(paint, byAlign)
+    }
+    const hit = byAlign[align]
+    if (hit !== undefined) {
+        return hit
+    }
+    // 第 2 段: paint の style キーは cellPaint が固定順で書くため JSON が決定的 (= intern キー)
+    const merged = { ...paint.style, justifyContent: alignToJustify(align) }
+    const key = JSON.stringify(merged)
+    let style = styleByKey.get(key)
+    if (style === undefined) {
+        // 有界: 上限で全消去 (CF memo と同じ規律 — 同値の再生成は identity を失うだけで正しさは不変)
+        if (styleByKey.size >= STYLE_INTERN_LIMIT) {
+            styleByKey.clear()
+        }
+        style = Object.freeze(merged)
+        styleByKey.set(key, style)
+    }
+    byAlign[align] = style
+    return style
+}
+
+/** Conditional-format capability pair (the root-built index and its memo — one rebuild key). / 条件付き書式の能力対 (root 構築の索引と memo — 同じ再構築キー)。 */
+export type CfCapability = { readonly indexRef: RefObject<CfIndex | null>; readonly memoRef: RefObject<CfMemo> }
+
+/** Memo handed to the painted-format seam when the CF capability is absent (never written: a null index returns before any memo use). / CF 能力なしのとき塗り書式合流点へ渡す memo (索引 null は memo に触れる前に返るため書込は起きない)。 */
+const NO_CF_MEMO: CfMemo = createCfMemo()
+
+/**
+ * The rich-cell patch of one cell: `data-aqsp-*` state attributes, the interned inline style
+ * (null = alignment undeclared) and the display value format of the painted format (identical to
+ * the base's — the CF vocabulary has no `value`; undefined without the format capability or for a
+ * value-less format), handed to the `children` renderer through the per-cell latch so the display
+ * costs no adapter read.
+ * セル 1 つのリッチセル差分: `data-aqsp-*` 状態属性 + intern 済みインライン style (null = 揃え能力なし) +
+ * 塗り書式の表示値書式 (base と同一 — CF 語彙に `value` は無い。書式能力なし / value なし書式は undefined)。
+ * 値書式はセル毎の掛け金で `children` レンダラーへ渡し、表示にアダプタ読みを払わない。
+ */
+export type RichCellProps = { readonly attrs: Readonly<Record<string, string>>; readonly style: CellStyle | null; readonly value: CellValueFormat | undefined }
+
+/**
+ * Single-entry latch carrying the display value format from `getCellProps` to `children` for
+ * the SAME cell — VirtualGrid calls `getCellProps(row, col)`, `getCell(row, col)` and
+ * `children(text, row, col)` back-to-back per rendered cell (its `renderRow` builds each cell
+ * element in one expression), so one mutable entry is enough and no per-cell allocation happens.
+ * Barrel-private; exported for the pins.
+ * `getCellProps` から `children` へ**同じセル**の表示値書式を運ぶ単一エントリの掛け金 — VirtualGrid は
+ * 描画セル毎に `getCellProps(row, col)` → `getCell(row, col)` → `children(text, row, col)` を連続で呼ぶ
+ * (`renderRow` がセル要素を 1 式で組む) ため、可変エントリ 1 つで足りセル毎の割当も起きない。
+ * バレル非公開 — ピン用に export。
+ */
+export type DisplayLatch = { row: number; col: number; value: CellValueFormat | undefined }
+
+/**
+ * Takes the latched display value format of (row, col). A latch written for another cell means
+ * the engine broke its per-cell call order (`getCellProps` must immediately precede the cell's
+ * renderer) — that is a contract violation, not a value to substitute, so it fails fast with a
+ * RangeError instead of re-reading the adapter. Barrel-private; exported for the pins.
+ * (row, col) の掛け金に置かれた表示値書式を取り出す。別セルの掛け金はエンジンがセル毎の呼び順
+ * (`getCellProps` がそのセルのレンダラーの直前) を破った契約違反であり代替値ではないため、アダプタを
+ * 再読せず RangeError で fail-fast する。バレル非公開 — ピン用に export。
+ */
+export const takeLatchedValue = (latch: DisplayLatch, row: number, col: number): CellValueFormat | undefined => {
+    // 掛け金は直前の getCellProps のセルと一致して初めて意味を持つ (不一致 = 呼び順の契約違反)
+    if (latch.row !== row || latch.col !== col) {
+        throw new RangeError(`[spreadsheet] cell renderer (${row}, ${col}) ran without its getCellProps (latched ${latch.row}, ${latch.col})`)
+    }
+    return latch.value
+}
+
+/**
+ * Resolves the rich-cell attributes and style of one cell (plan §4.2.11) — the ONE place the
+ * adapter's per-cell aspect reads happen, at most eight, every one behind its capability branch:
+ * (1) the painted format through `resolvePaintedFormat` (base ⊕ CF — the base by identity
+ * without the CF capability), (2) / (3) the next VISIBLE right / below neighbours' BASE formats
+ * for border ownership (CF never paints borders), (4) note, (5) comments, (6) hyperlink,
+ * (7) validation, and (8) the text through ONE lazy thunk shared by the auto alignment (align
+ * unset), the CF conditions and the invalid marker. The painted format's `value` is returned
+ * for the display (the `children` renderer never re-reads it). The alignment attribute is always emitted
+ * under the format capability (the v0.7 contract), the indicators only when present (an empty
+ * comment thread / a blank validated cell carry nothing), and `custom` validation rules are
+ * never evaluated at paint. Returns null for the v0.1 identity (no aspect declared — the text
+ * thunk is not even built) so the caller spreads nothing. Barrel-private; exported for the pins.
+ * セル 1 つのリッチセル属性と style を解決 (計画 §4.2.11) — アダプタのセル毎側面読みが起きる唯一の
+ * 場所で、最大 8 読み、全て能力分岐の内側: (1) `resolvePaintedFormat` 経由の塗り書式 (base ⊕ CF —
+ * CF 能力なしは base を identity で)、(2) / (3) 罫線所有のための次の**可視**な右 / 下隣の base 書式
+ * (CF は罫線を塗らない)、(4) ノート、(5) コメント、(6) リンク、(7) 検証、(8) 自動揃え (align 未設定) /
+ * CF 条件 / 不正マークが共有する遅延 thunk 1 本の text。塗り書式の `value` は表示用に返す (`children`
+ * レンダラーは再読しない)。揃え属性は書式能力下で常に出し (v0.7 契約)、
+ * 指標は存在するときだけ (空スレッド / 空文字の検証セルは何も出さない)、`custom` 検証規則は塗り時に
+ * 評価しない。v0.1 恒等 (側面未宣言 — text thunk も作らない) は null で、呼び手は何も spread しない。
+ * バレル非公開 — ピン用に export。
+ */
+export const resolveRichCellProps = (adapter: SpreadsheetDataAdapter, rowAxis: AxisModel, colAxis: AxisModel, cf: CfCapability | null, row: number, col: number): RichCellProps | null => {
+    // 能力未宣言は v0.1 の静的属性を厳密維持 (能力分岐 — 値フォールバックではない): 側面が 1 つも
+    // 宣言されていなければ属性も style も一切出さない。判定は塗り 5 側面のメンバー直接読み —
+    // aspectCapabilities のスナップショットはセル毎の塗りで短命 7 フィールド割当になるため組まない
+    // (生読み契約は直接判定でも同一で、後から宣言された能力は次の塗りに反映される)
+    if (adapter.getCellFormat === undefined && adapter.getCellNote === undefined && adapter.getCellComments === undefined && adapter.getCellHyperlink === undefined && adapter.getCellValidation === undefined) {
+        return null
+    }
+    // text は遅延 1 回読み (8 読み目 — align 未設定の自動揃え / CF 条件 / isVisiblyInvalid が同じ
+    // thunk を共有)。VirtualGrid からは渡されない (engine は children 用に別途読む)
+    const readText = lazyCellText(adapter, row, col)
+    const attrs: Record<string, string> = {}
+    let style: CellStyle | null = null
+    let value: CellValueFormat | undefined
+    if (adapter.getCellFormat !== undefined) {
+        // 読み 1: 塗り書式 = base ⊕ CF (唯一の合流点 — 索引は root の宣言能力、未指定は null で base のみ = v0.7)
+        const painted = resolvePaintedFormat(adapter, cf === null ? null : cf.indexRef.current, cf === null ? NO_CF_MEMO : cf.memoRef.current, row, col, readText)
+        // 表示の値書式は塗り書式のもの (= base の value — CF 語彙に value は無い)。children はこれを掛け金で受け取り再読しない
+        value = painted === undefined ? undefined : painted.value
+        // 唯一の揃え判定 (align 明示なら text を読まない)
+        const align = resolveCellAlign(painted, readText)
+        // 読み 2 / 3: 罫線所有の畳込み相手は次の**可視**隣接の base 書式 (非表示トラックは線を持たない)。
+        // 左端 / 上端 = 軸原点に接するセル (先行トラックが全て非表示なら offset 0)
+        const rightCol = nextVisibleIndex(colAxis, col, 1)
+        const belowRow = nextVisibleIndex(rowAxis, row, 1)
+        const paint = resolveCellPaint(painted, rightCol === null ? undefined : adapter.getCellFormat(row, rightCol), belowRow === null ? undefined : adapter.getCellFormat(belowRow, col), colAxis.offsetOf(col) === 0, rowAxis.offsetOf(row) === 0)
+        if (paint !== null) {
+            Object.assign(attrs, paint.attrs)
+        }
+        // 揃え属性は解決済み揃えが唯一の書き手 (paint の明示 align と同値なので上書きは衝突しない)
+        attrs["data-aqsp-align"] = align
+        style = internCellStyle(paint, align)
+    }
+    // 読み 4: ノート指標
+    if (adapter.getCellNote !== undefined && adapter.getCellNote(row, col) !== undefined) {
+        attrs["data-aqsp-note"] = ""
+    }
+    // 読み 5: コメント指標 (空スレッドは指標なし)
+    if (adapter.getCellComments !== undefined) {
+        const comments = adapter.getCellComments(row, col)
+        if (comments !== undefined && comments.length > 0) {
+            attrs["data-aqsp-comment"] = ""
+        }
+    }
+    // 読み 6: リンク指標 — 信頼境界 (ADR-10): 許可外スキームはリンク無し (開通 / copy / fill と同じ判定 —
+    // 指標だけリンクに見える不整合を作らない)。URL 解析の費用はリンクを持つセルに限る
+    if (adapter.getCellHyperlink !== undefined && normalizeAdapterHyperlink(adapter.getCellHyperlink(row, col)) !== undefined) {
+        attrs["data-aqsp-link"] = ""
+    }
+    // 読み 7 (+ 規則があれば text): 塗り時に判定できる規則だけの不正マーク (custom は評価しない)
+    if (adapter.getCellValidation !== undefined) {
+        const rule = adapter.getCellValidation(row, col)
+        if (rule !== undefined && isVisiblyInvalid(rule, readText())) {
+            attrs["data-aqsp-invalid"] = ""
+        }
+    }
+    return { attrs, style, value }
+}
+
+type GridBodyProps = {
+    adapter: SpreadsheetDataAdapter
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    viewStore: ViewStore
+    handleRef: RefObject<VirtualGridHandle | null>
+    /** Engine hit-test / listener target element (§6.4.3 — owned by Spreadsheet). / 選択エンジンのヒットテスト / リスナー対象 (所有は Spreadsheet)。 */
+    bodyRef?: RefObject<HTMLDivElement | null>
+    /** The consumer dataVersion prop (external half of renderVersion — §6.9-2). / renderVersion の外部成分。 */
+    dataVersion: number | undefined
+    /** Fenwick baseValue for the grid's column tree (§7-8 — behaviorOptions.defaultColWidth). / 列幅木の Fenwick baseValue (§7-8)。 */
+    defaultColumnWidth: number
+    /** Frozen leading columns (v0.5 — VirtualGrid frozenLeadingCols pass-through; engine-validated). / 先頭凍結列数 (v0.5 — エンジン検証の素通し)。 */
+    frozenColumns: number
+    /** Frozen leading rows (v0.6 — VirtualGrid frozenLeadingRows pass-through; engine-validated). / 先頭凍結行数 (v0.6 — エンジン検証の素通し)。 */
+    frozenRows: number
+    renderCell?: (ctx: RenderCellContext) => ReactNode
+    /** 2D scroll notification from the grid handle (the truth — §7-4). / グリッドハンドル発の 2 軸スクロール通知 (§7-4 の真実側)。 */
+    onScroll: (position: { x: number; y: number }) => void
+    onRangeChange: (range: VirtualGridRange) => void
+    /** Unified focus recovery for the bar bands (§6.8-3 — both scrollbars live inside the grid since v0.4). / バー帯のフォーカス回収 (§6.8-3 — v0.4 から両バーはグリッド内在)。 */
+    focusSink: () => void
+    /** Editing-session probe for the §6.8-3 commit gate. / §6.8-3 確定ゲート用の編集セッションプローブ。 */
+    isEditing: () => boolean
+    /** Commit gate — false aborts the bar press keeping the session. / 確定ゲート (false でバー押下中断・セッション維持)。 */
+    requestCommit: () => boolean
+    testId?: string
+    /** Test-only CellView re-render counter seam (§8.2). / テスト専用の再レンダー計数シーム。 */
+    __onCellRender?: ProfilerOnRenderCallback
+    /**
+     * v0.8 capability (with `cfMemoRef`): the root-built conditional-format index, rebuilt per
+     * (rules identity, renderVersion) and read fresh at every slice. Absent ⇒ the painted format
+     * is the adapter's base format (v0.7). Passing only one of the two refs is a RangeError.
+     * v0.8 能力 (`cfMemoRef` と対): root が (規則 identity, renderVersion) 毎に再構築する条件付き書式
+     * 索引 — 各スライスで鮮度読み。未指定 ⇒ 塗り書式 = アダプタの base 書式 (v0.7)。片方だけは RangeError。
+     */
+    cfIndexRef?: RefObject<CfIndex | null>
+    /** Companion memo of `cfIndexRef` (same rebuild key). / `cfIndexRef` と対の memo (同じ再構築キー)。 */
+    cfMemoRef?: RefObject<CfMemo>
+    /**
+     * v0.8 capability: formula-reference pointing probe. While pointing, a bar-band press is
+     * consumed (no commit, focus back to the sink — §4.2.11). Absent ⇒ the v0.7 gate.
+     * v0.8 能力: 参照ポインティングの判定。ポインティング中のバー帯押下は consume (確定せずシンクへ
+     * 焦点回収 — §4.2.11)。未指定 ⇒ v0.7 のゲート。
+     */
+    isPointing?: () => boolean
+}
+
+/**
+ * Owns the VirtualGrid wiring and the cell renderer (memo target). / VirtualGrid 結線とセルレンダラーの所有 (memo 対象)。
+ */
+const GridBodyInner = ({
+    adapter,
+    rowAxis,
+    colAxis,
+    viewStore,
+    handleRef,
+    bodyRef: externalBodyRef,
+    dataVersion,
+    defaultColumnWidth,
+    frozenColumns,
+    frozenRows,
+    renderCell,
+    onScroll,
+    onRangeChange,
+    focusSink,
+    isEditing,
+    requestCommit,
+    testId,
+    __onCellRender,
+    cfIndexRef,
+    cfMemoRef,
+    isPointing,
+}: GridBodyProps): ReactNode => {
+    const internalBodyRef = useRef<HTMLDivElement | null>(null)
+    // 外部 ref (エンジン結線用) と内部 ref の合成
+    const bodyRef = externalBodyRef ?? internalBodyRef
+    // 条件付き書式索引は索引 + memo の対でだけ意味を持つ (片方だけの結線は呼び手バグ — fail-fast)
+    if ((cfIndexRef === undefined) !== (cfMemoRef === undefined)) {
+        throw new RangeError("[spreadsheet] cfIndexRef and cfMemoRef must be passed together")
+    }
+    // 能力の対を 1 値へ (identity は 2 つの ref に追随 — 通常は不変)
+    const cf = useMemo((): CfCapability | null => (cfIndexRef === undefined || cfMemoRef === undefined ? null : { indexRef: cfIndexRef, memoRef: cfMemoRef }), [cfIndexRef, cfMemoRef])
+
+    // editVersion 購読 (renderVersion 配送 §6.9-2): v0.3 は useColumnWindow キーに乗せていたが、
+    // 列窓は VirtualGrid の所有になったため editVersion を直接購読する (再レンダー源はこれ 1 本)
+    const getEditSnapshot = useCallback(() => viewStore.get().editVersion, [viewStore])
+    const subscribe = useCallback((listener: () => void) => viewStore.subscribeCoalesced(listener), [viewStore])
+    const editVersion = useSyncExternalStore(subscribe, getEditSnapshot, getEditSnapshot)
+    // ?? 0 は必須 — 省略すると editVersion + undefined = NaN で deps が恒久安定し編集が映らなくなる
+    const renderVersion = editVersion + (dataVersion ?? 0)
+
+    // ---- VirtualGrid 結線 (identity 安定 — §6.9-4) ----
+    const getRowHeight = useCallback((row: number) => rowAxis.sizeOf(row), [rowAxis])
+    const getColWidth = useCallback((col: number) => colAxis.sizeOf(col), [colAxis])
+    const getCell = useCallback((row: number, col: number) => adapter.getCellText(row, col), [adapter])
+    // ARIA コンテナ属性 (identity は行列数にのみ追随)。型は行側と同型の狭い contentProps
+    const contentProps = useMemo(() => ({ role: "grid", "aria-rowcount": adapter.rowCount, "aria-colcount": adapter.colCount, "aria-multiselectable": true }) as const, [adapter.rowCount, adapter.colCount])
+    // 挙動オプション: 行木は identity 変化で再構築 (軸再構築追随)、列幅木も対称 + defaultColWidth
+    // (§7-8 — サンプリング省略の Fenwick baseValue)。pointerDragInputs はペン / タッチのみ
+    // (マウスドラッグは選択エンジンの所有)
+    const behaviorOptions = useMemo(() => ({ enableKeyboardNavigation: false, pointerDragInputs: ["pen", "touch"] as const, resetOnGetItemHeightChange: true, resetOnGetColWidthChange: true, defaultColWidth: defaultColumnWidth }), [defaultColumnWidth])
+    const scrollBarOptions = useMemo(() => ({ width: SCROLLBAR_WIDTH }), [])
+    // 表示値書式の掛け金 (getCellProps が書き、同じセルの children が直後に消費 — 番兵は届かない座標)
+    const displayLatchRef = useRef<DisplayLatch>({ row: -1, col: -1, value: undefined })
+    /**
+     * Cell attribute surface (§7-3 — the v0.3 CellView div contract moved onto the grid-owned
+     * cell node) + the v0.8 rich-cell paint (plan §4.2.11) resolved by `resolveRichCellProps`:
+     * null keeps the v0.1 static attributes byte-identical. Latches the resolved display value
+     * format for the cell's `children` call (the engine's per-cell call order) so the display
+     * pays no adapter read.
+     * セル属性面 (§7-3 — v0.3 の CellView div 契約をグリッド所有セルノードへ移植) + v0.8 のリッチセル塗り
+     * (計画 §4.2.11、`resolveRichCellProps` が解決): null は v0.1 の静的属性を厳密維持。解決した表示値書式は
+     * そのセルの `children` 呼び (エンジンのセル毎呼び順) のために掛け金へ置き、表示にアダプタ読みを払わない。
+     */
+    const getCellProps = useCallback(
+        (row: number, col: number) => {
+            const base = {
+                // aria-rowindex は行ラッパーと重複出力 (合法な上位集合) — セル単独が AT に読まれた際の行文脈補助 (§10-1)
+                role: "gridcell",
+                "aria-rowindex": row + 1,
+                "aria-colindex": col + 1,
+                "data-aqsp-cell": "",
+                "data-row": row,
+                "data-col": col,
+                className: "aqsp-cell",
+            }
+            const rich = resolveRichCellProps(adapter, rowAxis, colAxis, cf, row, col)
+            // 掛け金は毎セル更新 (v0.1 恒等の null でも座標を進める — children が消費するのは書式能力下だけ)
+            const latch = displayLatchRef.current
+            latch.row = row
+            latch.col = col
+            latch.value = rich === null ? undefined : rich.value
+            if (rich === null) {
+                return base as HTMLAttributes<HTMLDivElement>
+            }
+            return (rich.style === null ? { ...base, ...rich.attrs } : { ...base, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
+        },
+        [adapter, rowAxis, colAxis, cf],
+    )
+    /** Row attribute surface — carries the engine event gate (data-aqsp-cells §6.4.3-1). / 行属性面 — エンジンのイベントゲート (data-aqsp-cells) を運ぶ。 */
+    const getRowProps = useCallback(
+        (row: number) =>
+            ({
+                role: "row",
+                "aria-rowindex": row + 1,
+                "data-aqsp-row": row,
+                // data-aqsp-cells は選択エンジンの標的ゲート (§6.4.3-1) — グリッド内にはスクロール
+                // バーも同居しており、セル領域由来のイベントだけを機械へ通す (v0.3 の .aqsp-cells
+                // ラッパーの契約を行ラッパーへ移植 — 中間ノード 1 段の削減)
+                "data-aqsp-cells": "",
+                className: "aqsp-row",
+            }) as HTMLAttributes<HTMLDivElement>,
+        [],
+    )
+
+    // renderVersion は children identity に乗せる (§6.9-2): identity 変化が VirtualGrid の行
+    // レンダラーを作り替え、可視セル全再スライス (getCell 再読み) を駆動する — v0.3 の
+    // useColumnWindow キー方式と同じ配送保証
+    const children = useCallback(
+        (text: string, row: number, col: number): ReactNode => {
+            // renderVersion は識別子として参照する (identity-bust — 値そのものは使わない)
+            void renderVersion
+            // v0.7 表示形式: renderCell 指定時は素の text を素通し (escape hatch・組み込み値書式に優先)、
+            // 未指定時のみ値書式を表示文字列へ適用 (編集 / コピーは素の値のまま)。値書式は直前の
+            // getCellProps が掛け金へ置いた塗り書式の value (= base の value — CF 語彙に value は無い) で、
+            // アダプタは再読しない (書式能力なしは掛け金にも触れない v0.7 恒等)
+            let display = text
+            if (renderCell === undefined && adapter.getCellFormat !== undefined) {
+                display = formatCellValue(text, takeLatchedValue(displayLatchRef.current, row, col))
+            }
+            return <CellView row={row} col={col} text={display} renderCell={renderCell} __onCellRender={__onCellRender} />
+        },
+        [renderVersion, renderCell, __onCellRender, adapter],
+    )
+
+    return (
+        <div
+            ref={bodyRef}
+            className="aqsp-body"
+            data-aqsp-body=""
+            data-testid={testId ? `${testId}-body` : undefined}
+            onPointerDownCapture={(event) => {
+                // バー帯の統合ゲート (§6.8-3 — v0.4 でスクロールバー 2 本ともグリッド内在化):
+                // セル領域 (data-aqsp-cells) 由来は選択エンジンの所有 — 素通し。それ以外 (縦バー /
+                // 横バー帯 / 余白) は v0.3 HScrollBar と同一の 4 サイト共通ゲートを適用する
+                if (event.target instanceof Element && event.target.closest("[data-aqsp-cells]") !== null) {
+                    return
+                }
+                // mouse 限定: タッチはスクロールジェスチャ専用でシンク focus はモバイル OSK を招く
+                if (event.pointerType !== "mouse") {
+                    return
+                }
+                // 非主ボタンは押下の既定動作 (フォーカス移動) だけ止めて素通し — ネイティブメニューは
+                // preventDefault でも届き、止めないと root group へ逃げたフォーカスでキーボードが全滅する (R2 是正)
+                if (event.button !== 0) {
+                    event.preventDefault()
+                    return
+                }
+                // フォーカス回収の一本化 (§6.8-3): バー操作後も Ctrl+C が発火する状態を保つ。
+                // ❗ capture 必須 — ScrollBar のサム / トラック / 矢印ハンドラは合成 stopPropagation
+                // で終わるため、バブル側の親ハンドラは機能押下の全てで死にコードになる
+                event.preventDefault()
+                // 参照ポインティング中 (v0.8 §4.2.11): バー帯押下は確定させず consume してシンクへ焦点を
+                // 戻す (セッションと部分数式を保つ — 能力なしは v0.7 のゲートへ)
+                if (isPointing?.() === true) {
+                    event.stopPropagation()
+                    focusSink()
+                    return
+                }
+                // 編集中の requestCommit ゲート (§6.8-3): バーもフォーカス不動で focusout が発火
+                // しない — ここが唯一の確定経路。失敗は押下中断 (capture の stopPropagation で
+                // ScrollBar のサム / トラック処理を止め、セッションを維持する)
+                if (isEditing() && !requestCommit()) {
+                    event.stopPropagation()
+                    focusSink()
+                    return
+                }
+                focusSink()
+            }}>
+            <VirtualGrid<string>
+                ref={handleRef}
+                rowCount={adapter.rowCount}
+                colCount={adapter.colCount}
+                frozenLeadingCols={frozenColumns}
+                frozenLeadingRows={frozenRows}
+                getRowHeight={getRowHeight}
+                getColWidth={getColWidth}
+                getCell={getCell}
+                getCellProps={getCellProps}
+                getRowProps={getRowProps}
+                contentProps={contentProps}
+                behaviorOptions={behaviorOptions}
+                scrollBarOptions={scrollBarOptions}
+                callbackThrottleMs={0}
+                onScroll={onScroll}
+                onRangeChange={onRangeChange}
+                testId={testId}>
+                {children}
+            </VirtualGrid>
+        </div>
+    )
+}
+
+/** Memo boundary isolating the body from shell re-renders (§6.9-3). / shell 再レンダー隔離境界。 */
+export const GridBody = memo(GridBodyInner)