@aiquants/spreadsheet 0.8.0

package/src/selection/useSelectionEngine.ts

@@ -0,0 +1,687 @@
+/**
+ * @fileoverview Pointer state machine for cell selection (§6.4.3): single body listener,
+ * mouse-only, contextmenu delivery, rAF-coalesced drag rect, one setState per press. A
+ * Ctrl-press on a selected cell enters SUBTRACT mode (§3.2): the press writes nothing, the
+ * drag rect is styled via the getDragMode reader relay, and the pointerup confirms one
+ * reduceSelectionSubtract. The sink is structurally out of reach (overlay sibling of the
+ * body — §8.1 forbids unobservable guards, so no sink-exclusion code exists here). Produces
+ * isDragging/getDragMode/abortDrag for the keyboard Escape split (§6.6.2). Listeners are
+ * attached ONCE and read live params through a ref (paramsRef pattern) — effect re-runs
+ * mid-drag would call cleanupDrag and kill the drag on the press re-render. v0.8 (plan
+ * §4.2.8): formula POINTING is delegated — a primary cell press consults the distinct
+ * reference-drag owner (usePointDrag, through `pointDragRef`) BEFORE the commit gate, and a
+ * consumed press leaves selection / anchor / active frozen; while pointing, dblclick and the
+ * bar-band press are inert (consume + focusSink, no commit). v0.8 D-53 (spec 08 §11): a
+ * Ctrl / Meta primary press (no Shift) consults the pointer link-opening capability
+ * (`openHyperlinkAt`) before the append / subtract semantics — a consumed press freezes the
+ * selection and mutes the derived dblclick. All are capability params: absent = the v0.7
+ * press path byte-for-byte.
+ *
+ * セル選択の pointer ステートマシン (§6.4.3)。body 単一リスナー・mouse 限定・contextmenu 配送・
+ * rAF 合流ドラッグ矩形・押下 1 回 setState。選択済みセルへの Ctrl+押下は減算モード (§3.2) —
+ * press 非書込・矩形スタイルは getDragMode reader リレー配送・up で reduceSelectionSubtract を
+ * 1 回確定。シンクは overlay 内 (body の兄弟) で構造的に不到達のため除外ガードは持たない
+ * (§8.1)。isDragging / getDragMode / abortDrag をキーボード Escape 分担 (§6.6.2) へ供給する。
+ * リスナーは 1 回だけ結線し、最新パラメータは ref 経由で読む (effect 再実行はドラッグ中の
+ * cleanupDrag = ドラッグ即死を招くため)。v0.8 (計画 §4.2.8): 数式ポインティングは委譲 —
+ * 主ボタンのセル押下は commit ゲートより**先**に独立所有者 (usePointDrag、`pointDragRef` 経由)
+ * へ諮り、消費された押下は選択 / anchor / active を凍結したまま。ポインティング中の dblclick と
+ * バー帯押下は不活性 (consume + focusSink、commit なし)。v0.8 D-53 (分冊 08 §11): Ctrl / Meta
+ * 主ボタン押下 (Shift なし) は append / 減算判定より先にリンク開通能力 (`openHyperlinkAt`) へ諮り、
+ * 消費された押下は選択凍結 + 派生 dblclick 不活性。いずれも能力 param: 不在 = v0.7 の
+ * 押下経路と byte 同一。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellCoord, type CellRange, clampCoord, coordEquals, makeRange, rangeContains } from "../model/cellCoord.ts"
+import { viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
+import { reduceSelectionExtend, reduceSelectionPress, reduceSelectionSubtract, type SelectionState } from "./selectionState.ts"
+import { type AutoScroller, SCROLLER_ARM_THRESHOLD } from "./useAutoScroller.ts"
+
+/**
+ * Click-point caret resolution for the dblclick edit entry (ED-1 §6). Feature detection (NOT
+ * a value fallback): caretPositionFromPoint first, caretRangeFromPoint second. Adoption needs
+ * a text-node hit whose ancestor cell matches the hit-tested coordinate — pointer capture
+ * retargets dblclick to the body, so event.target is useless here. undefined = caret-at-end
+ * (the v0.1 behavior).
+ * ダブルクリック編集のクリック位置キャレット解決 (ED-1 §6)。機能検出 (値フォールバックでは
+ * ない): caretPositionFromPoint → caretRangeFromPoint の順。採用条件はテキストノード命中 +
+ * 祖先セルのヒットテスト座標一致 — capture 再ターゲットで dblclick の event.target は body に
+ * なるため使えない。undefined = キャレット末尾 (v0.1 挙動)。
+ */
+const caretIndexFromPoint = (clientX: number, clientY: number, cell: CellCoord): number | undefined => {
+    let offsetNode: Node | null = null
+    let offset = 0
+    if (typeof document.caretPositionFromPoint === "function") {
+        const position = document.caretPositionFromPoint(clientX, clientY)
+        if (position === null) {
+            return undefined
+        }
+        offsetNode = position.offsetNode
+        offset = position.offset
+    } else if (typeof document.caretRangeFromPoint === "function") {
+        const range = document.caretRangeFromPoint(clientX, clientY)
+        if (range === null) {
+            return undefined
+        }
+        offsetNode = range.startContainer
+        offset = range.startOffset
+    } else {
+        return undefined // API なし (jsdom 等) — キャレット末尾へ
+    }
+    if (offsetNode === null || offsetNode.nodeType !== Node.TEXT_NODE) {
+        return undefined
+    }
+    // 命中ノードの祖先セルとヒットテスト座標を照合 (隣接セルのテキストノード命中を採用しない)
+    const cellElement = offsetNode.parentElement?.closest("[data-aqsp-cell]") ?? null
+    if (cellElement === null || Number(cellElement.getAttribute("data-row")) !== cell.row || Number(cellElement.getAttribute("data-col")) !== cell.col) {
+        return undefined
+    }
+    return offset
+}
+
+/**
+ * Body-relative pointer → cell hit test with the §7-4 freshness hierarchy: the handle's
+ * synchronous scroll position, the press-cached body rect, one zoom division at the boundary
+ * and the frozen-partition inverse mapping on both axes, clamped into the grid. ONE mapping
+ * shared by the cell engine and the reference-drag owner (usePointDrag — plan §4.1.18) so an
+ * identical pointer resolves to an identical cell in both. null = unmeasurable (no handle /
+ * rect, detached scroll sentinel, empty axis).
+ * body 基準のポインタ → セルのヒットテスト (§7-4 の鮮度序列): ハンドルの同期スクロール位置・
+ * 押下時計測の body rect・境界で 1 回だけのズーム除算・両軸の凍結パーティション逆写像、グリッド内
+ * へクランプ。セルエンジンと参照ドラッグ所有者 (usePointDrag — 計画 §4.1.18) が共有する単一写像
+ * (同じポインタは両者で同じセルに解決する)。null = 計測不能 (ハンドル / rect 不在、detached 番兵、
+ * 空軸)。
+ */
+export const hitTestCell = (handle: VirtualGridHandle | null, rect: DOMRect | null, rowAxis: AxisModel, colAxis: AxisModel, zoom: number, clientX: number, clientY: number): CellCoord | null => {
+    if (handle === null || rect === null) {
+        return null
+    }
+    // 両軸ともハンドルの getScrollPosition (同期・最新の内部 ref 読み — §7-4 の鮮度序列)。
+    // ストアは v0.4 から位置を運ばない (rAF 写像の複製は押下が古い行 / 列へ着地する)
+    const { x: hx, y: vy } = handle.getScrollPosition()
+    if (vy < 0 || hx < 0) {
+        return null
+    }
+    if (rowAxis.totalSize() === 0 || colAxis.totalSize() === 0) {
+        return null
+    }
+    // ズーム境界 (v0.3): rect / client は視覚 px、軸は論理 px — 差分を zoom で 1 回だけ除算。
+    // 行 / 列とも凍結パーティション逆写像 (v0.6 / v0.5 計画 §2 — 帯サイズ未満は静的凍結帯、以上は + スクロール)
+    const frozen = handle.getFrozenSize()
+    return clampCoord({ row: viewportYToRow(rowAxis, (clientY - rect.top) / zoom, vy, frozen.height), col: viewportXToCol(colAxis, (clientX - rect.left) / zoom, hx, frozen.width) }, rowAxis.count, colAxis.count)
+}
+
+type UseSelectionEngineParams = {
+    /** Zoom scale reader (v0.3): client px = logical px × zoom — divide client deltas once at this boundary. / ズーム倍率 reader (v0.3)。client px = 論理 px × zoom — client 差分はこの境界で 1 回だけ除算する。 */
+    zoomRef: RefObject<number>
+    /** Rewire gate: wiring sleeps while the grid is empty and re-attaches on the non-empty transition (§6.9-1 empty branch). / 空グリッド間は結線を眠らせ、非空遷移で再結線するゲート。 */
+    enabled: boolean
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    handleRef: RefObject<VirtualGridHandle | null>
+    bodyRef: RefObject<HTMLElement | null>
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    /** Imperative selection read via ref (direct state reads are the stale-closure defect class — §6.4.3-3). / ref 経由の命令読み。 */
+    getSelection: () => SelectionState
+    /** The §6.9-1 Spreadsheet wrapper (raw setState is forbidden). / Spreadsheet のラッパー (生 setState 禁止)。 */
+    setSelection: (next: SelectionState) => void
+    focusSink: () => void
+    /** Drag-rect direct writer (null hides the resident node). / ドラッグ矩形の直書き (null = 非表示 — 常設ノードの表示制御)。 */
+    onDragFrame: (range: CellRange | null) => void
+    /** The sole contextmenu delivery channel, relayed to onCellContextMenu (kind: "pointer"). / onCellContextMenu へ横流しする唯一の配送チャネル。 */
+    onContextMenuSelect: (cell: CellCoord, event: MouseEvent) => void
+    /** The sole dblclick-to-edit channel (§6.4.3-7); caretIndex = the ED-1 click-point caret (undefined = caret-at-end). / ダブルクリック → editing(edit) 開始の唯一のチャネル。caretIndex は ED-1 のクリック位置キャレット (undefined = 末尾)。 */
+    onRequestEdit: (cell: CellCoord, caretIndex?: number) => void
+    /** ED-1 adoption gate (condition (c)) — PER-CELL: true only when the cell's DISPLAY text equals its raw canonical text (renderCell absent AND the cell's format leaves the string unchanged), so the click-point offset maps 1:1; false skips the caret computation entirely. / ED-1 採用ゲート (条件 (c)) — **セル単位**: 表示テキスト === 素の正準文字列のセルだけ true (クリック offset が 1:1 で写像可能)。false は計算自体をスキップ。 */
+    caretFromPointEnabled: (cell: CellCoord) => boolean
+    /**
+     * Composite drag probe across ALL machines (cell + both headers) for the contextmenu
+     * freeze gate — the engine's own draggingRef misses header drags, and a body right-click
+     * mid-header-drag would break the frozen-state contract (contextmenu is not retargeted by
+     * pointer capture).
+     * 全機械 (セル + 両ヘッダー) 合成のドラッグ判定 — contextmenu 凍結ゲート用。自機の
+     * draggingRef だけではヘッダードラッグ中の body 右クリックが凍結契約を破る。
+     */
+    isAnyDragging: () => boolean
+    autoScroller: AutoScroller
+    /** §8.2 repaint edges: press-after-flag + cleanup-end (fill-handle visibility re-evaluation). / §8.2 の repaint エッジ (press 直後 + cleanup 末尾 — fill ハンドル可視の再評価)。 */
+    repaintOverlay: () => void
+    /**
+     * v0.8 capability (plan §4.2.8): the reference-drag owner consulted BEFORE the commit gate
+     * on a primary cell press — a ref because usePointDrag is built after the engine (the root
+     * assigns it at render). Undefined / null current = no pointing press path (v0.7 identity).
+     * v0.8 能力 (計画 §4.2.8): 主ボタンのセル押下で commit ゲートより先に諮る参照ドラッグ所有者
+     * — usePointDrag はエンジンより後に構築されるため ref (root が render 時に代入)。undefined /
+     * current null = ポインティング押下経路なし (v0.7 恒等)。
+     */
+    pointDragRef?: RefObject<{ onPointerDown: (event: PointerEvent) => boolean } | null>
+    /**
+     * v0.8 capability: the editor's live pointing predicate (evaluated at the decision point —
+     * never cached). While true, dblclick does not open an editor and a bar-band / dead-space
+     * press only re-focuses the sink (no commit). Undefined = v0.7 identity.
+     * v0.8 能力: エディタの live ポインティング述語 (判断点でその場評価 — キャッシュしない)。true
+     * の間 dblclick はエディタを開かず、バー帯 / 死空間の押下はシンクの再フォーカスだけ (commit
+     * なし)。undefined = v0.7 恒等。
+     */
+    getPointing?: () => boolean
+    /**
+     * v0.8 capability (spec 08 §11 D-53): pointer hyperlink opening, consulted on a Ctrl / Meta
+     * primary cell press (Shift excluded — Ctrl+Shift stays extend) BEFORE the append / subtract
+     * semantics. true = the pressed cell carried a hyperlink and the host navigation fired — the
+     * press is consumed with selection / anchor / active frozen and the derived dblclick opens no
+     * editor; false = no link, the press continues as append / subtract. Undefined (host without
+     * `onHyperlinkOpen`) = the append / subtract press path byte-for-byte.
+     * v0.8 能力 (分冊 08 §11 D-53): Ctrl / Meta 主ボタンのセル押下 (Shift なし — Ctrl+Shift は extend
+     * のまま) で append / 減算判定より**先**に諮るポインタのリンク開通。true = 押下セルにリンクがあり
+     * ホスト遷移が発火 — 押下は消費され選択 / anchor / active は凍結、派生 dblclick もエディタを開か
+     * ない。false = リンク無し (押下は append / 減算へ続行)。undefined (`onHyperlinkOpen` 未宣言の
+     * ホスト) = append / 減算の押下経路と byte 同一。
+     */
+    openHyperlinkAt?: (cell: CellCoord) => boolean
+}
+
+/** Producer side of the Escape split (§6.6.2). / Escape 分担の生産側。 */
+export type SelectionEngine = {
+    isDragging: () => boolean
+    /**
+     * Live styling mode of the in-flight drag rect (§3.2 mode reader-ref relay): "subtract"
+     * only during a cell-machine subtract drag; "point" is reported by the reference-drag owner
+     * (usePointDrag — this engine never returns it; the union is shared so every owner has the
+     * same shape). Read per onDragFrame call by the Spreadsheet relay — the autoscroller's
+     * construction-time-fixed writer cannot carry it per call.
+     * 飛行中ドラッグ矩形のライブスタイルモード (§3.2 の mode reader ref 方式)。"subtract" は
+     * セル機械の減算ドラッグ中のみ、"point" は参照ドラッグ所有者 (usePointDrag) だけが返す
+     * (本エンジンは返さない — 全所有者が同形になるよう union を共有)。Spreadsheet のリレーが
+     * onDragFrame 呼びごとに読む — autoscroller の構築時固定 writer は per-call で運べないため。
+     */
+    getDragMode: () => "add" | "subtract" | "point"
+    /** Aborts with pre-press restore (Escape / capture loss). / 押下前復元つき中断。 */
+    abortDrag: () => void
+    /**
+     * Cancels WITHOUT restore — for sheet switch, where dragBeforeRef holds the OLD sheet's
+     * coordinates and restoring would leak an out-of-bounds selection into the new axes.
+     * 復元なしの取り消し — シート切替用 (dragBeforeRef は旧シート座標で、復元すると新軸へ
+     * 範囲外選択が漏れる)。
+     */
+    cancelDrag: () => void
+}
+
+/**
+ * Wires the pointer machine onto the body element.
+ * body 要素へ pointer 機械を結線する。
+ */
+export const useSelectionEngine = (params: UseSelectionEngineParams): SelectionEngine => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const draggingRef = useRef(false)
+    const dragBeforeRef = useRef<SelectionState | null>(null)
+    const bodyRectRef = useRef<DOMRect | null>(null)
+    const pointerRef = useRef({ clientX: 0, clientY: 0 })
+    const dragRafRef = useRef<number | null>(null)
+    const capturedPointerRef = useRef<number | null>(null)
+    /** `buttons` reported by the press — the primary bit vanishing on a captured move is the chorded primary release (R4). / 押下時の `buttons` (主ビットの消失 = chord 中の主ボタン解放)。 */
+    const pressButtonsRef = useRef(0)
+    /** Per-drag range-building closure shared by the move rAF and the autoscroller tick (single construction point). / ドラッグ毎の矩形構築クロージャ (move rAF と tick の共有 — 単一構築点)。 */
+    const buildRangeRef = useRef<((hover: CellCoord) => CellRange) | null>(null)
+    /** Subtract-mode flag for the in-flight drag (§3.2 — cleared on EVERY primary-mouse pointerdown DELIVERED TO THIS ELEMENT incl. refused presses, re-assigned by the accepted press, reset by cleanupDrag: as long as the press stream reaches this element, no stale true survives into a later confirm; an element-bypassing release belongs to the accepted self-healing dangling class). / 飛行中ドラッグの減算モードフラグ (§3.2 — **この要素へ配送される**主ボタン押下ごとに必ず掃除 (拒否押下含む) + 受理 press で再代入 + cleanupDrag でもリセット。押下列がこの要素へ届く限り stale true は後続確定まで生存できない — 要素を迂回するリリース列は許容済みの宙吊り自己修復クラス)。 */
+    const subtractModeRef = useRef(false)
+    /** Subtract-drag rect origin (§3.2 — press writes nothing, so selection.anchor would be the STALE previous anchor). / 減算ドラッグの矩形起点 (§3.2 — press 非書込のため selection.anchor は旧値 = stale anchor 事故の遮断)。 */
+    const subtractPressCellRef = useRef<CellCoord | null>(null)
+    /** Last pointerdown's pointer type (for the dblclick mouse gate — dblclick carries no pointerType). / 直近 pointerdown の種別 (dblclick の mouse 判定用)。 */
+    const lastPointerTypeRef = useRef<string>("")
+    /**
+     * Whether the last pointerdown originated in the cells area — the dblclick gate. dblclick
+     * CANNOT be gated on its own target: pointer capture retargets pointerup AND the derived
+     * dblclick to the capture element (the body), so a real-browser cell double-click arrives
+     * with target = body (empirically confirmed) while a scrollbar double-click still needs
+     * rejecting.
+     * 直近 pointerdown がセル領域由来か (dblclick 用ゲート)。dblclick は自身の target で判定
+     * できない — pointer capture が pointerup と派生 dblclick を capture 要素 (body) へ再ターゲット
+     * するため、実ブラウザのセルダブルクリックは target=body で届く (実測)。スクロールバーの
+     * ダブルクリックは引き続き拒否が必要。
+     */
+    const lastPressInCellsRef = useRef(false)
+    /**
+     * Whether the last primary press was consumed by the pointer link opening (D-53) — the
+     * derived dblclick must not open an editor (the press was not a selection gesture). Cleared
+     * on every delivered primary mouse press like `subtractModeRef`.
+     * 直近の主ボタン押下がリンク開通で消費されたか (D-53) — 派生 dblclick はエディタを開かない
+     * (押下は選択ジェスチャではない)。`subtractModeRef` と同じく配送される主ボタン押下ごとに掃除。
+     */
+    const lastPressOpenedLinkRef = useRef(false)
+
+    /** Hit test with the freshness hierarchy (§6.4.3-3) over the press-cached body rect — the shared mapping. / 鮮度序列準拠のヒットテスト (押下時計測の body rect 上) — 共有写像。 */
+    const hitTest = useCallback((clientX: number, clientY: number): CellCoord | null => {
+        const { handleRef, rowAxis, colAxis, zoomRef } = paramsRef.current
+        return hitTestCell(handleRef.current, bodyRectRef.current, rowAxis, colAxis, zoomRef.current, clientX, clientY)
+    }, [])
+
+    /** Scroller armed flag (armed after >= SCROLLER_ARM_THRESHOLD px of real movement — not at press, not on jitter; press-time self-heal resets it like subtractModeRef). / スクローラー武装フラグ (押下でなく累計 SCROLLER_ARM_THRESHOLD px 以上の実移動で武装。subtractModeRef と同じ押下時自己修復でリセット)。 */
+    const scrollerArmedRef = useRef(false)
+    /** Drag-anchor column for the frozen home-territory rule. / 凍結ホームテリトリー規則用のアンカー列。 */
+    const dragAnchorColRef = useRef<number | null>(null)
+    /** Drag-anchor row for the frozen home-territory rule (row twin). / 凍結ホームテリトリー規則用のアンカー行 (縦双子)。 */
+    const dragAnchorRowRef = useRef<number | null>(null)
+    /** Press point for the arming distance gate (the fill machine's FILL_ARM_THRESHOLD twin). / 武装距離ゲート用の押下点 (fill 機械の FILL_ARM_THRESHOLD 双子)。 */
+    const scrollerPressPointRef = useRef({ clientX: 0, clientY: 0 })
+
+    /** Idempotent drag cleanup (§6.4.3-8). / 冪等な後始末。 */
+    const cleanupDrag = useCallback(() => {
+        const { autoScroller, bodyRef, onDragFrame } = paramsRef.current
+        draggingRef.current = false
+        dragBeforeRef.current = null
+        buildRangeRef.current = null
+        scrollerArmedRef.current = false
+        dragAnchorColRef.current = null
+        dragAnchorRowRef.current = null
+        subtractModeRef.current = false
+        subtractPressCellRef.current = null
+        if (dragRafRef.current !== null) {
+            cancelAnimationFrame(dragRafRef.current)
+            dragRafRef.current = null
+        }
+        autoScroller.stop()
+        const body = bodyRef.current
+        if (body !== null && capturedPointerRef.current !== null) {
+            if (body.hasPointerCapture?.(capturedPointerRef.current)) {
+                body.releasePointerCapture(capturedPointerRef.current)
+            }
+        }
+        capturedPointerRef.current = null
+        // ドラッグ矩形を hidden へ (常設ノード — §6.7.2-3)
+        onDragFrame(null)
+        // cleanup 末尾の repaint エッジ (§8.2 — クリック航行でハンドルが恒久不可視になる回帰の閉塞)
+        paramsRef.current.repaintOverlay()
+    }, [])
+
+    /** Aborts an in-flight drag, restoring the pre-press state (Escape). / 押下前状態への中断復元。 */
+    const abortDrag = useCallback(() => {
+        if (!draggingRef.current) {
+            return
+        }
+        const before = dragBeforeRef.current
+        if (before !== null) {
+            paramsRef.current.setSelection(before)
+        }
+        cleanupDrag()
+    }, [cleanupDrag])
+
+    const { enabled, bodyRef } = params
+    useEffect(() => {
+        const body = bodyRef.current
+        // enabled は空グリッドの間 false — 非空遷移で deps が変わり、実 DOM が揃った後に再結線される
+        // (ref identity は不変のため、これ無しでは空マウント時の null bail が永久に固定される)
+        if (!enabled || body === null) {
+            return
+        }
+
+        // §6.4.3-1 のシンク除外ガードは置かない: シンクは overlay 内 (= body の兄弟) にあり、
+        // シンク上のポインタイベントは構造的に body リスナーへ到達しない (§8.1 — 観測不能ガード禁止)。
+        // トポロジが変わって到達するようになった場合は統合テストの番兵 (シンク標的 press) が落ちる
+
+        /**
+         * Cell-area target gate: the pane also hosts virtualscroll's vertical scrollbar INSIDE
+         * this body element, and its stopPropagation is React-synthetic (dispatched above the
+         * body) so it cannot shield these NATIVE listeners — a thumb press would replace the
+         * selection with a bogus cell under the bar. Only events originating in our own cells
+         * container enter the machine.
+         * セル領域標的ゲート。body 内には virtualscroll の縦スクロールバーが同居し、その
+         * stopPropagation は合成 (body より上で発火) のため native リスナーを遮れない —
+         * サム押下がバー下の偽セルへ選択を置換してしまう。自前のセルコンテナ由来のイベント
+         * だけを機械へ通す。
+         */
+        const isCellAreaTarget = (target: EventTarget | null): boolean => target instanceof Element && target.closest("[data-aqsp-cells]") !== null
+
+        const onPointerDown = (event: PointerEvent) => {
+            const p = paramsRef.current
+            // 主ボタン mouse 押下は領域を問わず最上流で stale 減算フラグを掃除する (§3.2 の
+            // 二重遮断の完全形 — 領域外 / 編集ゲート拒否 / hitTest null で中断される押下でも
+            // 必ず走る。宙吊りジェスチャ (capture 失敗 + 領域外リリース) が残した旧フラグで
+            // 後続の up が減算確定する経路の閉塞)
+            if (event.pointerType === "mouse" && event.button === 0) {
+                subtractModeRef.current = false
+                subtractPressCellRef.current = null
+                lastPressOpenedLinkRef.current = false
+            }
+            lastPressInCellsRef.current = isCellAreaTarget(event.target)
+            if (!lastPressInCellsRef.current) {
+                // セル領域外 (縦バー / ペイン死空間) の mouse 主ボタン押下: 選択機械には入れないが、
+                // preventDefault + focusSink でフォーカスはシンクに留める (§6.8-3 の第 4 サイト)。
+                // preventDefault を怠ると mousedown 既定が最近傍 focusable (root) へフォーカスを移し、
+                // onRootFocus は relatedTarget = シンク (in-root) で抑制 → 選択が armed に見えたまま
+                // キーボードが全滅する無音状態になる。v0.4 からは GridBody の capture 統合ゲート
+                // (§6.8-3 — 両バー内在化) が同一要素で先行するため、本分岐は同型の第 2 層 (多層防御)。
+                // touch / ペンは素通し (スクロールジェスチャを守る)。mouse 非主ボタンは既定のフォーカス移動
+                // だけ止めて素通し (ネイティブメニューは preventDefault でも届く — R2 是正)。
+                if (event.pointerType === "mouse") {
+                    event.preventDefault()
+                    if (event.button !== 0) {
+                        return
+                    }
+                    // ポインティング中 (v0.8 §4.2.8 / 設計 v4 §7): バー帯 / 死空間は consume + focusSink
+                    // だけ — 数式を確定せず参照も挿入しない (能力分岐: 未宣言なら従来の commit ゲートへ)
+                    if (p.getPointing?.()) {
+                        p.focusSink()
+                        return
+                    }
+                    // 編集中の requestCommit ゲート (§6.8-3): 縦バー / 死空間もフォーカス不動で
+                    // focusout が発火しない (コーナー / ヘッダーと同型)。v0.4 では GridBody capture が
+                    // 先行確定するため通常ここでは既に非編集 — 拒否経路も capture 側の stopPropagation
+                    // が本リスナーごと止める。以下は capture 層が外れた場合の自衛 (同型に維持する)
+                    if (p.isEditing() && !p.requestCommit()) {
+                        event.stopPropagation()
+                        p.focusSink()
+                        return
+                    }
+                    p.focusSink()
+                }
+                return
+            }
+            // dblclick (MouseEvent — pointerType を持たない) の mouse 判定用に直近の押下種別を記録
+            // (mouse ゲートより先 — touch 押下も記録してから弾く)
+            lastPointerTypeRef.current = event.pointerType
+            if (event.pointerType !== "mouse") {
+                return // タッチ / ペンは virtualscroll のドラッグスクロールへ
+            }
+            if (event.button !== 0) {
+                // 右クリックは contextmenu ハンドラ (§6.4.3-4)。押下の既定動作 (mousedown のフォーカス移動)
+                // だけは止める — 止めないと最近傍 focusable の root group へフォーカスが逃げ、onRootFocus は
+                // in-root 移動として抑制するため右クリック後のキーボードが全滅する。preventDefault しても
+                // contextmenu イベントとネイティブメニューは届く (実ブラウザ実証 — R2 是正)
+                event.preventDefault()
+                return
+            }
+            // --- ポインティング (数式参照挿入 — v0.8 §4.2.8): 独立所有者 usePointDrag に commit ゲート
+            //     より**先**に諮る。消費されたら選択 / active / anchor は凍結のまま (§4.1.18)。能力分岐:
+            //     ref 未配線 / 所有者未充填 / 述語不成立は従来の押下経路へ素通し (v0.7 恒等) ---
+            const pointDrag = p.pointDragRef === undefined ? null : p.pointDragRef.current
+            if (pointDrag?.onPointerDown(event)) {
+                return
+            }
+            // 編集中の外クリック: commit 成功後に押下処理 (失敗なら中断 — §6.4.3-2)。拒否時は
+            // preventDefault が必須: 押下の既定動作 (mousedown のフォーカス移動) が root group へ
+            // フォーカスを逃がし、セッション生存中は onRootFocus が再進入 rearm を行わないため
+            // 「セッションは維持されているのに Escape も打鍵もシンクへ届かない」宙吊りになる
+            if (p.isEditing() && !p.requestCommit()) {
+                event.preventDefault()
+                p.focusSink()
+                return
+            }
+            // bodyRect は押下で 1 回計測しドラッグ中はキャッシュ (§6.4.3-3 のレイアウト読み規律)
+            bodyRectRef.current = body.getBoundingClientRect()
+            const cell = hitTest(event.clientX, event.clientY)
+            if (cell === null) {
+                return
+            }
+            // 押下時 preventDefault (テキスト選択 / フォーカス移動の抑止) + フォーカス回収 (§6.4.3-6)
+            event.preventDefault()
+            p.focusSink()
+            // リンク開通 (v0.8 分冊 08 §11 D-53): append / 減算と同じチョード形 (Ctrl / Meta、Shift なし)
+            // はまずリンク開通に諮る — 押下セルにリンクがあれば選択 / anchor / active を凍結したまま
+            // 消費する。Ctrl+Shift は extend 優先 (減算判定の append && !extend と同型)、能力未宣言は
+            // 述語ごと不在で従来経路 (能力分岐 — 値フォールバックではない)
+            if ((event.ctrlKey || event.metaKey) && !event.shiftKey && p.openHyperlinkAt?.(cell) === true) {
+                lastPressOpenedLinkRef.current = true
+                return
+            }
+            const before = p.getSelection()
+            dragBeforeRef.current = before
+            const extend = event.shiftKey
+            const append = event.ctrlKey || event.metaKey
+            // 減算モード判定 (§3.2): Ctrl のみ (append && !extend — Ctrl+Shift は extend 優先で
+            // Excel 同等) + 押下セルが選択済み。減算は press では書き込まない (up 確定 1 回)。
+            // フラグは無条件代入 (通常押下が false へ戻す — cleanupDrag と合わせた二重遮断)
+            const subtract = append && !extend && before.ranges.some((range) => rangeContains(range, cell))
+            subtractModeRef.current = subtract
+            subtractPressCellRef.current = subtract ? cell : null
+            if (!subtract) {
+                // 押下は reduceSelectionPress をその場で 1 回 setState (Excel は押下即座に選択が変わる)
+                p.setSelection(reduceSelectionPress(before, cell, { extend, append }))
+            }
+            draggingRef.current = true
+            // press 直後の repaint エッジ (§8.2 — フラグ成立後にハンドル可視条件を再評価させる)
+            p.repaintOverlay()
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            capturedPointerRef.current = event.pointerId
+            pressButtonsRef.current = event.buttons
+            try {
+                // jsdom は合成イベントの pointerId で InvalidPointerId を投げうる — 実ブラウザでは成功。
+                // capture 失敗時も pointermove/up は body リスナーで受かるため機能劣化は端外 drop のみ
+                body.setPointerCapture(event.pointerId)
+            } catch {
+                capturedPointerRef.current = null
+            }
+            // buildRange はドラッグ開始時の起点を閉じ込め、ref にも保持する — pointermove rAF と
+            // オートスクローラー tick の両書き手がこの 1 クロージャを共有する (単一構築点。二重に
+            // 別実装を持つとヘッダー側のスパン昇格のような差分が将来ドリフトする)。減算モードの
+            // 起点は押下セル (press 非書込のため selection.anchor は旧値 — §3.2)
+            const dragAnchor = subtract ? cell : p.getSelection().anchor
+            buildRangeRef.current = (hover) => makeRange(dragAnchor, hover)
+            // スクローラーは押下では起動しない (初回の実 pointermove で武装 — fill 機械と同
+            // ポリシーへ統一。押下起動は左ゾーン内の press だけで毎フレームのドレインになり、
+            // v0.5 の帯基準左ゾーンでは凍結セルのクリックが可動帯の勝手な左スクロールに化ける
+            // — R5 実証是正)。anchor 列はホームテリトリー規則のため武装時に渡す
+            dragAnchorColRef.current = dragAnchor.col
+            dragAnchorRowRef.current = dragAnchor.row
+            // 押下時自己修復 (subtractModeRef と同じ規約 — R5 是正): 宙吊りジェスチャ (capture
+            // 不能 + 要素外解放) が残した旧スクローラーと stale 武装フラグを毎押下で必ず掃除する。
+            // 放置すると旧コンテキスト (旧 anchorCol) が次ジェスチャを駆動し続ける (実証 −128px)
+            p.autoScroller.stop()
+            scrollerArmedRef.current = false
+            scrollerPressPointRef.current = { clientX: event.clientX, clientY: event.clientY }
+        }
+
+        /**
+         * Whether the event belongs to the pointer that started the drag (mouse-only contract
+         * §6.4.1 holds on ALL drag phases — touch/pen events run CONCURRENTLY with a mouse drag
+         * because they pass through to virtualscroll's drag scroll, and an ungated touch
+         * pointerup would confirm the mouse drag at the finger's position).
+         * ドラッグを開始したポインタ本人か (mouse 限定契約は全フェーズで保つ — touch / pen は
+         * virtualscroll のドラッグスクロールへ素通しされ mouse ドラッグと並行に流れるため、
+         * ゲート無しの touch pointerup が指の位置でドラッグを確定してしまう)。
+         */
+        const isOwnPointer = (event: PointerEvent): boolean => (capturedPointerRef.current !== null ? event.pointerId === capturedPointerRef.current : event.pointerType === "mouse")
+
+        const applyPointerMove = (event: PointerEvent) => {
+            if (!(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            // 距離ゲートつき武装 (押下起動の廃止 + fill 機械の FILL_ARM_THRESHOLD 双子 — R5 是正):
+            // 実クリックは押下〜解放間に 1〜3px のジッタや座標同値のキャプチャエコーを含むため、
+            // 「move 1 発」では武装させない (右端ゾーンのクリックが +32px/frame のドレインに化ける
+            // — 実証 +96px)。押下点から累計 4px 以上の実移動のみが武装させる
+            if (!scrollerArmedRef.current && buildRangeRef.current !== null) {
+                const armDx = Math.abs(event.clientX - scrollerPressPointRef.current.clientX)
+                const armDy = Math.abs(event.clientY - scrollerPressPointRef.current.clientY)
+                if (Math.max(armDx, armDy) >= SCROLLER_ARM_THRESHOLD) {
+                    scrollerArmedRef.current = true
+                    paramsRef.current.autoScroller.start({ getPointerPosition: () => pointerRef.current, buildRange: buildRangeRef.current, anchorCol: dragAnchorColRef.current ?? undefined, anchorRow: dragAnchorRowRef.current ?? undefined })
+                }
+            }
+            // rAF 合流でドラッグ矩形を直書き (React 未介在 — §6.4.3-5)
+            if (dragRafRef.current === null) {
+                dragRafRef.current = requestAnimationFrame(() => {
+                    dragRafRef.current = null
+                    const buildRange = buildRangeRef.current
+                    if (!draggingRef.current || buildRange === null) {
+                        return
+                    }
+                    const p = paramsRef.current
+                    const hover = hitTest(pointerRef.current.clientX, pointerRef.current.clientY)
+                    if (hover !== null) {
+                        p.onDragFrame(buildRange(hover))
+                    }
+                })
+            }
+        }
+
+        const onPointerMove = (event: PointerEvent) => {
+            applyPointerMove(event)
+            // chord 中の主ボタン解放 (R4 是正): 主ボタン保持中に 2 本目を押した状態で主ボタンを離すと、
+            // その解放は pointerup でなく pointermove (buttons から主ビットが消える) で届き、最後の
+            // pointerup は非主ボタンのため確定ゲートを通らず、暗黙 capture 解放 → lostpointercapture
+            // で押下前状態へ巻き戻されていた。押下時に主ビットを報告したポインタが主ビットを失った
+            // move は主ボタンの解放 = ここで確定する (jsdom の合成 move は buttons 0 だが押下も 0)
+            if (draggingRef.current && isOwnPointer(event) && (pressButtonsRef.current & 1) !== 0 && (event.buttons & 1) === 0) {
+                confirmAt(event)
+            }
+        }
+
+        const onPointerUp = (event: PointerEvent) => {
+            // 主ボタンのリリースのみ確定する (非主ボタンの up は同一 pointerId のため isOwnPointer を
+            // 通過してしまう — ドラッグ中の右ボタンリリースでの早期確定と、宙吊りジェスチャを
+            // 右クリックが旧フラグのまま確定する事故の両方を閉塞。Excel も左リリースのみ確定)
+            if (event.button !== 0 || !(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            confirmAt(event)
+        }
+
+        /** Confirms the in-flight gesture at the event position (primary release — pointerup or chorded move). / 飛行中ジェスチャの確定 (主ボタン解放 — pointerup または chord 中の move)。 */
+        const confirmAt = (event: PointerEvent) => {
+            const p = paramsRef.current
+            const hover = hitTest(event.clientX, event.clientY)
+            // hitTest null (軸空化等の縮退) は書込スキップ + cleanup でジェスチャ全体が無音に落ちる
+            if (hover !== null) {
+                const pressCell = subtractPressCellRef.current
+                if (subtractModeRef.current && pressCell !== null) {
+                    // 減算確定は setSelection 1 回 (§3.2 — press 非書込と対の up 単一書込)
+                    p.setSelection(reduceSelectionSubtract(p.getSelection(), makeRange(pressCell, hover), pressCell))
+                } else {
+                    // pointerup で reduceSelectionExtend を setState (等価なら identity bail — 二重発火なし)
+                    p.setSelection(reduceSelectionExtend(p.getSelection(), hover))
+                }
+            }
+            cleanupDrag()
+        }
+
+        const onLostPointerCapture = (event: PointerEvent) => {
+            // capture 喪失 (ウィンドウ外 drop 等) は押下前状態へ復元 (§6.4.3-8)。所有 pointerId
+            // 限定 — ScrollPane の touch capture 解放 (lostpointercapture は bubbles) が body 内から
+            // 浮上して mouse ドラッグを無関係に巻き戻すのを防ぐ。capture 未成立 (null) の自分の
+            // 喪失イベントは存在しないため null は常に無視
+            if (!draggingRef.current || capturedPointerRef.current === null || event.pointerId !== capturedPointerRef.current) {
+                return
+            }
+            abortDrag()
+        }
+
+        const onContextMenu = (event: MouseEvent) => {
+            const p = paramsRef.current
+            if (!isCellAreaTarget(event.target)) {
+                return // スクロールバー右クリック等はネイティブメニューへ素通し (選択も通知も不変)
+            }
+            // mouse 限定 (§6.4.1 — touch / pen の長押し contextmenu で armed 選択を破壊しない)。
+            // contextmenu は MouseEvent で pointerType を持たない — dblclick と同じく直近
+            // pointerdown の種別で判定する (実ブラウザは mouse 右クリックの前に必ず pointerdown
+            // (button 2) を配送し、その記録は button ゲートより前で行われる)
+            if (lastPointerTypeRef.current !== "mouse") {
+                return
+            }
+            // ドラッグ中の同時右クリックは無視 (Excel 同等) — 素通しするとドラッグ中に選択が置換され
+            // 「ドラッグ中は state 凍結・確定は pointerup の 1 回」の契約が破れる。判定は合成面
+            // (ヘッダードラッグ中の body 右クリックも凍結対象 — contextmenu は capture 非追従)
+            if (p.isAnyDragging()) {
+                return
+            }
+            // 編集中のエディタ右クリックは textarea ネイティブメニューへ素通し (シンクは body の
+            // 兄弟のためここへは到達しない)。編集中の body 右クリックは requestCommit ゲート
+            // (確定後に続行・失敗なら中断)
+            if (p.isEditing() && !p.requestCommit()) {
+                p.focusSink()
+                return
+            }
+            // フォーカス回収 (§6.8-3 の contextmenu 面): 右ボタン押下は preventDefault 済みでフォーカスは
+            // 動かないが、グリッド外にフォーカスがある状態からの右クリック (選択の置換が起きる) でも
+            // キーボードをグリッドへ呼び込む — v0.7 まで rearmSink の select() 副作用が偶然担っていた
+            // 回収の明示化 (R2 是正)。consumer のメニューが後段で自前要素へ focus すればそちらが勝つ
+            p.focusSink()
+            bodyRectRef.current = body.getBoundingClientRect()
+            const cell = hitTest(event.clientX, event.clientY)
+            if (cell === null) {
+                return
+            }
+            // 順序は置換 → 通知 (Excel 意味論 — メニューは置換後の新選択に作用する)。
+            // 選択の置換だけが条件付き: 選択外なら置換、選択内なら不変 (§6.4.1)
+            const selection = p.getSelection()
+            const inSelection = selection.ranges.some((range) => rangeContains(range, cell))
+            if (!inSelection) {
+                p.setSelection(reduceSelectionPress(selection, cell, { extend: false, append: false }))
+            }
+            // 無条件通知 (唯一の配送チャネル — 選択内右クリック = consumer メニューの最頻フローでも発火)
+            p.onContextMenuSelect(cell, event)
+            // preventDefault しない (ネイティブメニューは妨げない — §6.4.1)
+        }
+
+        const onDblClick = (event: MouseEvent) => {
+            const p = paramsRef.current
+            // target でなく直近押下の由来で判定 (capture 再ターゲットで target=body になる — 上記 ref 参照)
+            if (!lastPressInCellsRef.current) {
+                return
+            }
+            // dblclick は MouseEvent で pointerType を持たない — 直近 pointerdown の種別で mouse 限定を
+            // 貫く (§6.4.1「mouse のみ」/ §6.4.3-7「dblclick (mouse 左)」。タッチのダブルタップで
+            // 編集開始しない — タッチはスクロール専用)。既知特性: 2 回目 click と dblclick の間に
+            // 割り込んだ touch tap が記録を上書きすると正当な mouse ダブルクリックを 1 回落とす
+            // (安全方向 — 誤って開くことはない)。Phase 3 で実害が出る場合は pointerId 照合へ
+            if (lastPointerTypeRef.current !== "mouse") {
+                return
+            }
+            // ポインティング中の dblclick は無視 (v0.8 §4.2.8 — 1 回目の押下が参照を挿入済みで、
+            // 2 回目のクリックはトークン置換。セッションを二重に開かない。能力分岐: 未宣言は従来どおり)
+            if (p.getPointing?.()) {
+                return
+            }
+            // リンク開通で消費された押下の派生 dblclick は編集を開かない (D-53 — 押下は選択ジェスチャ
+            // ではなく、active も動いていない。修飾なしの次の押下がフラグを掃除して従来へ戻す)
+            if (lastPressOpenedLinkRef.current) {
+                return
+            }
+            bodyRectRef.current = body.getBoundingClientRect()
+            const cell = hitTest(event.clientX, event.clientY)
+            if (cell === null) {
+                return
+            }
+            // 1 回目の click は押下処理で単独選択 + active 化済み — active セルのみ編集開始 (§6.4.3-7)。
+            // ED-1: クリック位置キャレットを startEdit 前のこの時点で解決する (シンクは 1px 待機で
+            // セル DOM が最前面 — 編集開始後はシンクがセルを覆い caretPositionFromPoint が届かない)
+            if (coordEquals(p.getSelection().active, cell)) {
+                p.onRequestEdit(cell, p.caretFromPointEnabled(cell) ? caretIndexFromPoint(event.clientX, event.clientY, cell) : undefined)
+            }
+        }
+
+        body.addEventListener("pointerdown", onPointerDown)
+        body.addEventListener("pointermove", onPointerMove)
+        body.addEventListener("pointerup", onPointerUp)
+        body.addEventListener("lostpointercapture", onLostPointerCapture)
+        body.addEventListener("contextmenu", onContextMenu)
+        body.addEventListener("dblclick", onDblClick)
+        return () => {
+            body.removeEventListener("pointerdown", onPointerDown)
+            body.removeEventListener("pointermove", onPointerMove)
+            body.removeEventListener("pointerup", onPointerUp)
+            body.removeEventListener("lostpointercapture", onLostPointerCapture)
+            body.removeEventListener("contextmenu", onContextMenu)
+            body.removeEventListener("dblclick", onDblClick)
+            cleanupDrag()
+        }
+    }, [enabled, bodyRef, hitTest, cleanupDrag, abortDrag])
+
+    return useMemo(
+        () => ({
+            isDragging: () => draggingRef.current,
+            // セル機械は add / subtract だけ ("point" は usePointDrag が返し、root の合成面が配る)
+            getDragMode: (): "add" | "subtract" | "point" => (subtractModeRef.current ? "subtract" : "add"),
+            abortDrag,
+            cancelDrag: cleanupDrag,
+        }),
+        [abortDrag, cleanupDrag],
+    )
+}