@aiquants/spreadsheet 0.8.0

package/src/header/useHeaderResize.ts

@@ -0,0 +1,598 @@
+/**
+ * @fileoverview Header resize / unhide machine (§7 PT-1). ONE hook wires BOTH bands
+ * (machine count in the §7.4 composite = 1). The band gets ONE wire-once native
+ * capture-phase pointerdown (strips carry no listeners — virtual re-render unmounts would
+ * kill captures) which records lastPointerTypeRef FIRST, gates on primary mouse, dispatches
+ * via closest() and steals from the selection machine ONLY on a hit. Drags write a
+ * rAF-coalesced guideline through the overlay writer; the cell sizes change ONLY at the up
+ * commit (Excel-like). Commits run through the resizeTracks batch seam after the pure
+ * `gateResizeEntries` (resizeGates.ts — the §7.2 post-application zero-guard, the ADR-12
+ * track-count gate and the §5.4(b) row-axis hidden-total gate in one place) plus the §7.2
+ * fan-out (full-span selection). Band dblclick = column autofit (canvas measureText over the
+ * visible window, measured-cell gate; v0.8 §4.2.10 — every cell is measured in its PAINTED
+ * font (base ⊕ width-relevant conditional formats: bold / italic setters plus every `stopIfTrue`
+ * barrier so the sliced walk stops where paint stops, sliced per column),
+ * bucketed by font key so `ctx.font` is assigned once per distinct font) / row default-height
+ * restore / unhide marker restore. While the editor is pointing at a formula reference
+ * (v0.8 §4.2.10) a strip press is consumed (focus back to the sink, no gesture, no commit).
+ *
+ * ヘッダーリサイズ / unhide 機械 (§7 PT-1)。単一フックが両帯を結線 (§7.4 の機械勘定 = 1)。
+ * 帯へ wire-once の native capture pointerdown を 1 本 (ストリップはリスナーを持たない —
+ * 仮想再レンダーの unmount が capture を殺す)。lastPointerTypeRef の記録が最初、主ボタン
+ * mouse ゲート、closest() ディスパッチ、命中時のみ選択機械から奪う。ドラッグは overlay
+ * writer 経由の rAF 合流ガイドラインのみ描き、セル実サイズは up 確定でだけ変わる。確定は
+ * 純関数 `gateResizeEntries` (resizeGates.ts — §7.2 の適用後 0 化ガード + ADR-12 トラック数
+ * ゲート + §5.4(b) の行軸非表示総数ゲートを 1 箇所に) を通した resizeTracks バッチシーム +
+ * ファンアウト (全スパン選択)。帯 dblclick = 列 autofit (可視ウィンドウの canvas measureText +
+ * 計測セル数ゲート。v0.8 §4.2.10 — 各セルを**塗り書式**のフォント (base ⊕ 幅に効く条件付き書式 =
+ * bold / italic 設定規則と stopIfTrue の障壁 — 走査が塗りと同じ位置で止まる — を列毎にスライス) で
+ * 計り、フォントキーでバケット化して `ctx.font` の
+ * 代入を異なりフォント毎 1 回にする) / 行は既定行高復元 / unhide マーカーは既定サイズ復元。
+ * 参照ポインティング中 (v0.8 §4.2.10) のストリップ押下は consume (シンクへ焦点、ジェスチャも
+ * 確定もなし)。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import type { AxisModel } from "../model/axisModel.ts"
+import type { SpreadsheetOperation } from "../model/cellCoord.ts"
+import { type CellFormat, formatCellValue } from "../model/cellFormat.ts"
+import { buildCfIndex, createCfMemo, resolvePaintedFormat, widthRelevantRules } from "../model/conditionalFormat.ts"
+import type { SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import type { ViewStore } from "../model/viewStore.ts"
+import type { ResizeGuide } from "../overlay/SelectionOverlay.tsx"
+import type { SelectionState } from "../selection/selectionState.ts"
+import type { SelectionEngine } from "../selection/useSelectionEngine.ts"
+import { gateResizeEntries, type ResizeEntry, ROW_FANOUT_DIVISOR, ROW_HIDDEN_LIMIT } from "./resizeGates.ts"
+
+/** Autofit horizontal padding: cell padding 4+4 + right border 1 (px). / autofit の水平パディング (セル padding 4+4 + 右罫 1)。 */
+const AUTOFIT_PADDING = 9
+/**
+ * Autofit measured-cell limit divisor (§13 budget row (e) DESIGN RETURN, measured): 100k
+ * DISTINCT-string measureText runs ~794ms in headless Chromium (the 50-string rotation that
+ * flattered the first bench sits at ~186ms via Blink's shape cache) — the 300ms class holds
+ * only up to ~25k distinct measurements, so autofit gates at maxOperationCells / 4.
+ * autofit 計測上限の除数 (§13 予算行 (e) の設計返却 — 実測起点)。異なり文字列 10 万件の
+ * measureText は headless Chromium で ~794ms (初回ベンチの 50 文字列巡回は shape cache で
+ * ~186ms に化けていた)。300ms 級は異なり ~2.5 万計測まで — autofit は maxOperationCells / 4
+ * でゲートする。
+ */
+const AUTOFIT_MEASURE_DIVISOR = 4
+
+type UseHeaderResizeParams = {
+    /** 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>
+    /** Inert gate: false = no listeners at all (§11 enableResizeUI opt-out / empty grid). / 不活性ゲート (§11 の opt-out / 空グリッド)。 */
+    enabled: boolean
+    colBandRef: RefObject<HTMLElement | null>
+    rowBandRef: RefObject<HTMLElement | null>
+    colAxis: AxisModel
+    rowAxis: AxisModel
+    viewStore: ViewStore
+    handleRef: RefObject<VirtualGridHandle | null>
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    focusSink: () => void
+    getSelection: () => SelectionState
+    adapter: SpreadsheetDataAdapter
+    /** Autofit adoption condition: renderCell unspecified (custom DOM defeats measureText — §10 deviation). / autofit 採用条件 (renderCell 未指定)。 */
+    autofitEnabled: boolean
+    defaultRowHeight: number
+    defaultColumnWidth: number
+    maxOperationCells: number
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    /** The batch application seam (Spreadsheet-owned — bump/repaint once per batch). / バッチ適用シーム (Spreadsheet 所有)。 */
+    resizeTracks: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void
+    /** Guideline writer relay (overlay-owned positioner). / ガイドライン writer リレー (positioner は overlay 所有)。 */
+    writeResizeGuide: (guide: ResizeGuide | null) => void
+    /** §8.2 repaint edges: called after the press flag set and at cleanup end. / §8.2 の repaint エッジ (press 直後 + cleanup 末尾)。 */
+    repaintOverlay: () => void
+    /**
+     * The editor's live pointing predicate (v0.8 §4.2.10): true ⇒ a strip press is consumed
+     * (stopPropagation + preventDefault + focusSink) without a gesture or a commit gate.
+     * エディタの生きたポインティング述語 (v0.8 §4.2.10): true ならストリップ押下は consume
+     * (stopPropagation + preventDefault + focusSink) でジェスチャも commit ゲートも走らない。
+     */
+    isPointing: () => boolean
+}
+
+/**
+ * The canvas `font` shorthand of a painted format over the band's computed style: italic /
+ * bold / pt size (× 4/3 px, like cellPaint) / family from the format, the band's values
+ * otherwise. Interned per format object (the paint intern keeps one object per distinct
+ * painted format, so this is one string per distinct font).
+ * 塗り書式の canvas `font` 短縮形 (帯の computed style の上に italic / bold / pt サイズ (× 4/3 px —
+ * cellPaint と同式) / フォント族を重ねる)。書式 object 毎に intern (塗り intern が書式毎に 1 object を
+ * 保つので、異なりフォント毎に 1 文字列)。
+ */
+const fontKeyOf = (painted: CellFormat, fontKeys: WeakMap<CellFormat, string>, bandStyle: CSSStyleDeclaration): string => {
+    const cached = fontKeys.get(painted)
+    if (cached !== undefined) {
+        return cached
+    }
+    // 真偽値は厳密 true のみ (fail-soft — cellPaint と同じ判定)
+    const style = painted.italic === true ? "italic" : bandStyle.fontStyle
+    const weight = painted.bold === true ? "bold" : bandStyle.fontWeight
+    // pt は cellPaint と同じ × 4/3 で px へ (非有限 / 非正は帯の既定のまま)
+    const size = typeof painted.fontSize === "number" && Number.isFinite(painted.fontSize) && painted.fontSize > 0 ? `${(painted.fontSize * 4) / 3}px` : bandStyle.fontSize
+    const family = typeof painted.fontFamily === "string" && painted.fontFamily !== "" ? painted.fontFamily : bandStyle.fontFamily
+    const font = `${style} ${weight} ${size} ${family}`
+    fontKeys.set(painted, font)
+    return font
+}
+
+/** One in-flight gesture. / 飛行中ジェスチャ 1 件。 */
+type ResizeGesture = {
+    axis: "row" | "col"
+    kind: "resize" | "unhide"
+    index: number
+    initialSize: number
+    startClientX: number
+    startClientY: number
+}
+
+/**
+ * Wires the resize/unhide machine onto both header bands; returns the §7.4 composite surface.
+ * 両ヘッダー帯へリサイズ / unhide 機械を結線し、§7.4 の合成面を返す。
+ */
+export const useHeaderResize = (params: UseHeaderResizeParams): SelectionEngine => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const draggingRef = useRef(false)
+    const gestureRef = useRef<ResizeGesture | null>(null)
+    const pendingSizeRef = useRef(0)
+    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)
+    /** The band that holds the capture (release target). / capture を持つ帯 (解放先)。 */
+    const capturedBandRef = useRef<HTMLElement | null>(null)
+    const guideRafRef = useRef<number | null>(null)
+    /** Last pointerdown's pointer type (dblclick carries no pointerType — v0.1 実測). / 直近 pointerdown の種別 (dblclick の mouse 判定用)。 */
+    const lastPointerTypeRef = useRef<string>("")
+    /** Attached window listeners for the drag duration. / ドラッグ期間だけ張る window リスナー。 */
+    const windowListenersRef = useRef<{ move: (e: PointerEvent) => void; up: (e: PointerEvent) => void } | null>(null)
+
+    /** Whether the event belongs to the capturing pointer (mouse-only contract on all phases). / 所有ポインタ照合 (mouse 限定契約の全フェーズ維持)。 */
+    const isOwnPointer = useCallback((event: PointerEvent): boolean => (capturedPointerRef.current !== null ? event.pointerId === capturedPointerRef.current : event.pointerType === "mouse"), [])
+
+    /** Idempotent cleanup: guideline off + capture release + window listeners off + the §8.2 cleanup repaint edge. / 冪等な後始末 (ガイドライン消灯 + §8.2 の cleanup repaint エッジ)。 */
+    const cleanupDrag = useCallback(() => {
+        const p = paramsRef.current
+        draggingRef.current = false
+        gestureRef.current = null
+        if (guideRafRef.current !== null) {
+            cancelAnimationFrame(guideRafRef.current)
+            guideRafRef.current = null
+        }
+        p.writeResizeGuide(null)
+        const listeners = windowListenersRef.current
+        if (listeners !== null) {
+            window.removeEventListener("pointermove", listeners.move)
+            window.removeEventListener("pointerup", listeners.up)
+            windowListenersRef.current = null
+        }
+        const band = capturedBandRef.current
+        if (band !== null && capturedPointerRef.current !== null && band.hasPointerCapture?.(capturedPointerRef.current)) {
+            band.releasePointerCapture(capturedPointerRef.current)
+        }
+        capturedBandRef.current = null
+        capturedPointerRef.current = null
+        p.repaintOverlay()
+    }, [])
+
+    /** Full-span predicate: SOME single range covers the whole cross axis and contains the index (§3.3 と同一述語). / 全交差軸スパン述語。 */
+    const isFullSpanRange = useCallback((axis: "row" | "col", range: SelectionState["ranges"][number]): boolean => {
+        const p = paramsRef.current
+        return axis === "col" ? range.startRow === 0 && range.endRow === p.rowAxis.count - 1 : range.startCol === 0 && range.endCol === p.colAxis.count - 1
+    }, [])
+
+    /**
+     * Fan-out targets (§7.2): when the pressed track belongs to a full-span range, ALL tracks
+     * of all full-span ranges (hidden included — implicit unhide, Excel-compatible); the
+     * ADR-12 gate counts BEFORE materializing (duplicate spans counted as-is, conservative).
+     * Returns null when rejected.
+     * ファンアウト対象 (§7.2)。押下トラックが全スパンレンジ所属なら全スパンレンジ群の全トラック
+     * (非表示含む — 暗黙再表示)。ADR-12 ゲートは実体化前に保守側で数える。拒否時は null。
+     */
+    const collectTargets = useCallback(
+        (axis: "row" | "col", pressedIndex: number): number[] | null => {
+            const p = paramsRef.current
+            const ranges = p.getSelection().ranges.filter((range) => isFullSpanRange(axis, range))
+            const inFanOut = ranges.some((range) => (axis === "col" ? pressedIndex >= range.startCol && pressedIndex <= range.endCol : pressedIndex >= range.startRow && pressedIndex <= range.endRow))
+            if (!inFanOut) {
+                return [pressedIndex]
+            }
+            // 実体化前の保守カウント (重複スパンは重複のまま数え、上限判定を保守側に倒す —
+            // countRangeCells と同じ流儀。帰結: 重複全スパンレンジでは実対象数が上限内でも
+            // 膨張カウントで拒否され得る + 通知 count も膨張値 — 意図した保守側逸脱)。
+            // 行軸は (f) の設計返却で 1/10 上限 (updateItemSize の per-call 補償コスト)
+            const count = ranges.reduce((sum, range) => sum + (axis === "col" ? range.endCol - range.startCol + 1 : range.endRow - range.startRow + 1), 0)
+            const limit = axis === "row" ? Math.floor(p.maxOperationCells / ROW_FANOUT_DIVISOR) : p.maxOperationCells
+            if (count > limit) {
+                p.onOperationRejected?.("resize", count, "limit")
+                return null
+            }
+            const targets = new Set<number>()
+            for (const range of ranges) {
+                const from = axis === "col" ? range.startCol : range.startRow
+                const to = axis === "col" ? range.endCol : range.endRow
+                for (let index = from; index <= to; index += 1) {
+                    targets.add(index)
+                }
+            }
+            return [...targets]
+        },
+        [isFullSpanRange],
+    )
+
+    /**
+     * Applies an entry batch through the pure gate (resizeGates.ts: count gate, rounding, the
+     * §7.2 post-application zero-guard on the pressed track, the §5.4(b) row-axis hidden-total
+     * gate) and then the resizeTracks seam once; a refusal goes to onOperationRejected("resize").
+     * 純関数ゲート (resizeGates.ts: 件数ゲート・丸め・§7.2 の押下トラック 0 化ガード・§5.4(b) の行軸
+     * 非表示総数ゲート) を通してから resizeTracks を 1 回呼ぶ。拒否は onOperationRejected("resize")。
+     */
+    const applyEntries = useCallback((axis: "row" | "col", rawEntries: readonly ResizeEntry[], pressedIndex: number | null): void => {
+        const p = paramsRef.current
+        const axisModel = axis === "col" ? p.colAxis : p.rowAxis
+        // ゲートは純関数 (§4.2.10 の委譲) — ヘッダー由来のサイズは常に有限 ≥ 0 なので RangeError 枝は到達しない
+        const result = gateResizeEntries(axisModel, rawEntries, pressedIndex, { maxOperationCells: p.maxOperationCells, rowHiddenLimit: ROW_HIDDEN_LIMIT, axisKind: axis })
+        if (!result.ok) {
+            p.onOperationRejected?.("resize", result.count, result.reason)
+            return
+        }
+        p.resizeTracks(axis, result.entries)
+    }, [])
+
+    /** The up commit: same-value skip → fan-out targets → batch apply. / up 確定 (同値スキップ → ファンアウト → バッチ適用)。 */
+    const commitResize = useCallback(
+        (gesture: ResizeGesture, newSize: number): void => {
+            if (newSize === gesture.initialSize) {
+                return // 同値スキップ (§7.2 — Excel の同値リリース均等化は非対応の逸脱)
+            }
+
+            // unhide ドラッグは対象 1 本 (境界に近い側から 1 本ずつ広げる — §7.3)
+            const targets = gesture.kind === "unhide" ? [gesture.index] : collectTargets(gesture.axis, gesture.index)
+            if (targets === null) {
+                return // ADR-12 拒否済み
+            }
+            applyEntries(
+                gesture.axis,
+                targets.map((index) => ({ index, size: newSize })),
+                gesture.index,
+            )
+        },
+        [collectTargets, applyEntries],
+    )
+
+    /** Column autofit (§7.3 / v0.8 §4.2.10): per-column canvas measurement over the visible window in each cell's painted font, bucketed by font key. / 列 autofit (可視ウィンドウをセルの塗りフォントで計測、フォントキーでバケット化)。 */
+    const autofitColumns = useCallback(
+        (band: HTMLElement, pressedIndex: number): void => {
+            const p = paramsRef.current
+            const targets = collectTargets("col", pressedIndex)
+            if (targets === null) {
+                return
+            }
+            // 可視ウィンドウ内の可視行 (幅 0 行は計測しない)
+            const { rowStart, rowEnd } = p.viewStore.get()
+            const last = Math.min(rowEnd, p.rowAxis.count - 1)
+            const visibleRows: number[] = []
+            for (let row = rowStart; row <= last; row += 1) {
+                if (p.rowAxis.sizeOf(row) > 0) {
+                    visibleRows.push(row)
+                }
+            }
+            // 計測対象の可視行がゼロ (命令 API 経由の全窓内非表示) は no-op — Excel も計測対象
+            // なしでは幅を変えない (0 計測 → 9px 潰しの破壊を作らない。R1(B) 所見)
+            if (visibleRows.length === 0) {
+                return
+            }
+            // 上限ゲートは計測セル数単位 (§7.3 — トラック数単位では 16k 列 × 可視 40 行が素通り
+            // する)。上限は autofit 専用の低い係数 (§13 (e) の設計返却 — 実測根拠は定数 docstring)
+            const measuredCells = targets.length * visibleRows.length
+            const measureLimit = Math.floor(p.maxOperationCells / AUTOFIT_MEASURE_DIVISOR)
+            if (measuredCells > measureLimit) {
+                p.onOperationRejected?.("resize", measuredCells, "limit")
+                return
+            }
+            // canvas 生成 + computed font 取得はジェスチャ 1 回につき 1 度 (§7.3)。font は
+            // ロングハンド合成の単一経路 (Firefox は font ショートハンドの computed 値を空で
+            // 返すため、合成だけが全ブラウザで決定的)
+            const context = document.createElement("canvas").getContext("2d")
+            if (context === null) {
+                return // 実ブラウザでは常に成立 (jsdom は 2d 未実装 — 計測面は E2E がピン)
+            }
+            const bandStyle = getComputedStyle(band)
+            // 既定フォント (書式なしセル) — 帯の computed style のロングハンド合成
+            const baseFont = `${bandStyle.fontStyle} ${bandStyle.fontWeight} ${bandStyle.fontSize} ${bandStyle.fontFamily}`
+            // CF は幅に効く規則 (bold / italic 設定) と stopIfTrue の障壁だけを 1 ジェスチャ 1 回抽出し列毎に
+            // スライスする (実測 155 → 56 ms)。障壁を残すため走査は塗りと同じ位置で止まり bold / italic が
+            // 厳密一致する。getConditionalFormats は getCellFormat を要する (root がマウント時に保証)
+            const cfRules = p.adapter.getConditionalFormats === undefined ? null : widthRelevantRules(p.adapter.getConditionalFormats())
+            const memo = createCfMemo()
+            const fontKeys = new WeakMap<CellFormat, string>()
+            // フォントキー毎のバケット (列 index + 表示文字列): ctx.font の代入は異なりフォント毎に 1 回
+            const buckets = new Map<string, { col: number; text: string }[]>()
+            for (const col of targets) {
+                const colIndex = cfRules === null ? null : buildCfIndex(cfRules.filter((rule) => rule.ranges.some((range) => col >= range.startCol && col <= range.endCol)))
+                for (const row of visibleRows) {
+                    // 計測対象は**画面に描かれる表示文字列** (v0.7 — 値書式適用後)。素の getCellText を測ると
+                    // 通貨 "￥1,234,567" が素値 "1234567" の幅に潰されて最上位桁ごと左クリップされる (誤読事故)。
+                    // 書式なしセルは formatCellValue が素通しするため従来と同一。interned フォーマッタにより
+                    // 計測ループ内の整形は O(1)/セル (キャッシュ前提 — 25k セル実測 32ms)
+                    const raw = p.adapter.getCellText(row, col)
+                    // 塗り書式 (base ⊕ 幅に効く CF) — raw は既読なので thunk は再読しない
+                    const painted = p.adapter.getCellFormat === undefined ? undefined : resolvePaintedFormat(p.adapter, colIndex, memo, row, col, () => raw)
+                    const font = painted === undefined ? baseFont : fontKeyOf(painted, fontKeys, bandStyle)
+                    const text = formatCellValue(raw, painted === undefined ? undefined : painted.value)
+                    const bucket = buckets.get(font)
+                    if (bucket === undefined) {
+                        buckets.set(font, [{ col, text }])
+                    } else {
+                        bucket.push({ col, text })
+                    }
+                }
+            }
+            // バケット毎にフォントを 1 回設定して計測 (E2E は ctx.font 代入回数 ≤ 異なりフォント数 + 1 を数える)
+            const widestByCol = new Map<number, number>()
+            for (const [font, cells] of buckets) {
+                context.font = font
+                for (const cell of cells) {
+                    const width = context.measureText(cell.text).width
+                    const widest = widestByCol.get(cell.col)
+                    if (widest === undefined || width > widest) {
+                        widestByCol.set(cell.col, width)
+                    }
+                }
+            }
+            const entries: ResizeEntry[] = []
+            for (const col of targets) {
+                const widest = widestByCol.get(col)
+                // 全空列は対象から外す (Excel の空列境界 dblclick は no-op — 9px 潰しを作らない)
+                if (widest !== undefined && widest > 0) {
+                    entries.push({ index: col, size: Math.ceil(widest) + AUTOFIT_PADDING })
+                }
+            }
+            if (entries.length === 0) {
+                return
+            }
+            applyEntries("col", entries, pressedIndex)
+        },
+        [collectTargets, applyEntries],
+    )
+
+    const { enabled, colBandRef, rowBandRef } = params
+    useEffect(() => {
+        const colBand = colBandRef.current
+        const rowBand = rowBandRef.current
+        if (!enabled || colBand === null || rowBand === null) {
+            return
+        }
+
+        /** Per-axis closest() selector (structural exclusivity of the two hooks). / 軸別 closest() セレクタ。 */
+        const selectorFor = (axis: "row" | "col"): string => (axis === "col" ? "[data-aqsp-col-resize], [data-aqsp-unhide]" : "[data-aqsp-row-resize], [data-aqsp-unhide]")
+
+        /** Resolves a strip hit to a gesture seed. / ストリップ命中のジェスチャ種解決。 */
+        const resolveHit = (axis: "row" | "col", target: EventTarget | null): { kind: "resize" | "unhide"; index: number } | null => {
+            if (!(target instanceof Element)) {
+                return null
+            }
+            const hit = target.closest(selectorFor(axis))
+            if (hit === null) {
+                return null
+            }
+            const isUnhide = hit.hasAttribute("data-aqsp-unhide")
+            const index = Number(hit.getAttribute(isUnhide ? "data-aqsp-unhide" : axis === "col" ? "data-aqsp-col-resize" : "data-aqsp-row-resize"))
+            return { kind: isUnhide ? "unhide" : "resize", index }
+        }
+
+        const applyWindowPointerMove = (event: PointerEvent) => {
+            if (!(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            const gesture = gestureRef.current
+            if (gesture === null) {
+                return
+            }
+            // ズーム境界 (v0.3): ドラッグ差分は視覚 px — 論理 px へ 1 回だけ除算して適用する
+            const delta = (gesture.axis === "col" ? event.clientX - gesture.startClientX : event.clientY - gesture.startClientY) / paramsRef.current.zoomRef.current
+            pendingSizeRef.current = Math.max(0, Math.round(gesture.initialSize + delta))
+            // ガイドラインは rAF 合流の直書き 1 ノードのみ (§7.2 — セル実サイズは確定まで不変)
+            if (guideRafRef.current === null) {
+                guideRafRef.current = requestAnimationFrame(() => {
+                    guideRafRef.current = null
+                    const live = gestureRef.current
+                    if (!draggingRef.current || live === null) {
+                        return
+                    }
+                    const p = paramsRef.current
+                    const axisModel = live.axis === "col" ? p.colAxis : p.rowAxis
+                    p.writeResizeGuide({ axis: live.axis, position: axisModel.offsetOf(live.index) + pendingSizeRef.current })
+                })
+            }
+        }
+
+        /** Confirms the in-flight resize at the pending size (primary release — pointerup or chorded move). / 飛行中リサイズの確定 (主ボタン解放 — pointerup または chord 中の move)。 */
+        const confirmResize = () => {
+            const gesture = gestureRef.current
+            const newSize = pendingSizeRef.current
+            cleanupDrag()
+            if (gesture !== null) {
+                commitResize(gesture, newSize)
+            }
+        }
+
+        const onWindowPointerMove = (event: PointerEvent) => {
+            applyWindowPointerMove(event)
+            // chord 中の主ボタン解放 (R4 是正 — 選択機械と同型): 主ビットを失った own move で、その move の
+            // 差分を反映した pendingSize で確定する
+            if (draggingRef.current && isOwnPointer(event) && (pressButtonsRef.current & 1) !== 0 && (event.buttons & 1) === 0) {
+                confirmResize()
+            }
+        }
+
+        const onWindowPointerUp = (event: PointerEvent) => {
+            // 主ボタンのリリースのみ確定 (選択機械と同じ閉塞 — 非主ボタン up は isOwnPointer を通過する)
+            if (event.button !== 0 || !(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            confirmResize()
+        }
+
+        /** Capture-phase press: record type → primary gate → closest dispatch → steal on hit (§7.1). / capture 押下 (記録 → 主ボタンゲート → closest → 命中時のみ奪取)。 */
+        const makePointerDown = (axis: "row" | "col", band: HTMLElement) => (event: PointerEvent) => {
+            const p = paramsRef.current
+            // 記録が最初 (記録は steal しない — touch 押下も記録してから弾く v0.1 同順)
+            lastPointerTypeRef.current = event.pointerType
+            if (event.pointerType !== "mouse") {
+                return // touch を steal すると 6px の死帯が virtualscroll のドラッグスクロールを壊す
+            }
+            if (event.button !== 0) {
+                // 非主ボタン: 既定のフォーカス移動だけ止め、奪わず (stopPropagation なし) 素通し (R2 是正)
+                event.preventDefault()
+                return
+            }
+            const hit = resolveHit(axis, event.target)
+            if (hit === null) {
+                return // 命中なしは選択機械へ (奪わない)
+            }
+            event.stopPropagation()
+            event.preventDefault()
+            // 参照ポインティング中 (v0.8 §4.2.10): consume してシンクへ焦点を戻すだけ (挿入なし・ジェスチャなし・
+            // commit ゲートも走らない — セッションと部分数式を保つ)
+            if (p.isPointing()) {
+                p.focusSink()
+                return
+            }
+            // §6.8-3 の第 6 サイト: 編集中は requestCommit ゲート (成功後に開始・失敗で中断)
+            if (p.isEditing() && !p.requestCommit()) {
+                p.focusSink()
+                return
+            }
+            p.focusSink()
+            const axisModel = axis === "col" ? p.colAxis : p.rowAxis
+            gestureRef.current = { axis, kind: hit.kind, index: hit.index, initialSize: axisModel.sizeOf(hit.index), startClientX: event.clientX, startClientY: event.clientY }
+            pendingSizeRef.current = gestureRef.current.initialSize
+            pressButtonsRef.current = event.buttons
+            draggingRef.current = true
+            // 自機フラグセット後の義務 press repaint (§8.2 の repaint エッジ — fill ハンドル消灯等)
+            p.repaintOverlay()
+            capturedPointerRef.current = event.pointerId
+            capturedBandRef.current = band
+            try {
+                // jsdom は InvalidPointerId を投げうる — 失敗時は mouse フォールバック (v0.1 両機械と同型)
+                band.setPointerCapture(event.pointerId)
+            } catch {
+                capturedPointerRef.current = null
+            }
+            const move = onWindowPointerMove
+            const up = onWindowPointerUp
+            windowListenersRef.current = { move, up }
+            window.addEventListener("pointermove", move)
+            window.addEventListener("pointerup", up)
+            // 押下位置の境界にガイドラインを即時表示
+            p.writeResizeGuide({ axis, position: axisModel.offsetOf(hit.index) + pendingSizeRef.current })
+        }
+
+        /** Band dblclick: autofit / unhide-restore (mouse via lastPointerTypeRef — dblclick has no pointerType). / 帯 dblclick (autofit / 復元)。 */
+        const makeDblClick = (axis: "row" | "col", band: HTMLElement) => (event: MouseEvent) => {
+            const p = paramsRef.current
+            if (lastPointerTypeRef.current !== "mouse") {
+                return
+            }
+            // 実ブラウザの dblclick はストリップに届かない: 押下でこの機械が帯へ pointer capture を
+            // 取るため up のターゲットは帯へ合成され、click / dblclick のターゲット (down / up の
+            // 共通祖先) も帯になる (Pointer Events / UI Events 仕様 — E2E 実証)。event.target が
+            // ストリップ外なら座標の実要素で解決し直す。ピッカーは帯の rootNode — shadow DOM ホスト
+            // では document 版がホスト要素を返し恒久 null になる (R1(D) 実証)。非 shadow は
+            // band.ownerDocument (別 realm 埋め込みでもグローバル document に依存しない)。
+            // elementFromPoint 非実装環境 (jsdom — レイアウトなし) は座標解決不能 = 命中なし扱い
+            // (throw させると consumer の jsdom テストが帯 dblclick で全滅する — R2(D) 実証)
+            const bandRoot = band.getRootNode()
+            const picker = bandRoot instanceof ShadowRoot ? bandRoot : band.ownerDocument
+            const direct = event.target instanceof Element && event.target.closest(selectorFor(axis)) !== null ? event.target : typeof picker.elementFromPoint === "function" ? picker.elementFromPoint(event.clientX, event.clientY) : null
+            const hit = resolveHit(axis, direct)
+            if (hit === null) {
+                return
+            }
+            event.stopPropagation()
+            // §6.8-3 の編集ゲートは dblclick 経路にも要る (R1(B) 実証): press の requestCommit が
+            // 拒否 (applyEdits throw でセッション維持) でも ブラウザは dblclick を合成配送する —
+            // 未確定セッションを跨いだ構造変異 (autofit / 復元) を作らない。ここで requestCommit を
+            // 再試行はしない: 同一ジェスチャの押下ゲート (2 押下) が既に確定を試みて拒否されたセッションで、
+            // 再試行は onEditRejected を 3 発目として重複発火させるだけ (R2 是正 — 1 押下 = 1 拒否)
+            if (p.isEditing()) {
+                p.focusSink()
+                return
+            }
+            if (hit.kind === "unhide") {
+                // 復元 = 既定サイズ (§7.3 — Excel の境界 dblclick autofit とは異なる単純化逸脱)
+                applyEntries(axis, [{ index: hit.index, size: axis === "col" ? p.defaultColumnWidth : p.defaultRowHeight }], null)
+                return
+            }
+            if (!p.autofitEnabled) {
+                return // renderCell 指定時は autofit 全体 no-op (§10 逸脱)
+            }
+            if (axis === "row") {
+                // 行 autofit = 既定行高への復元 (セルは単一行クリップ描画 — §10 逸脱)。ファンアウトは §7.2 と同じ対象規則
+                const targets = collectTargets("row", hit.index)
+                if (targets !== null) {
+                    applyEntries(
+                        "row",
+                        targets.map((index) => ({ index, size: p.defaultRowHeight })),
+                        hit.index,
+                    )
+                }
+                return
+            }
+            autofitColumns(band, hit.index)
+        }
+
+        const onLostPointerCapture = (event: PointerEvent) => {
+            // capture 喪失は中断 (pointerId 所有照合つき — v0.1 の両機械と同型。サイズ不変)
+            if (!draggingRef.current || capturedPointerRef.current === null || event.pointerId !== capturedPointerRef.current) {
+                return
+            }
+            cleanupDrag()
+        }
+
+        const colDown = makePointerDown("col", colBand)
+        const rowDown = makePointerDown("row", rowBand)
+        const colDbl = makeDblClick("col", colBand)
+        const rowDbl = makeDblClick("row", rowBand)
+        // capture: true — 選択機械の bubble リスナーより先に発火し、命中時のみ stopPropagation で奪う
+        colBand.addEventListener("pointerdown", colDown, { capture: true })
+        rowBand.addEventListener("pointerdown", rowDown, { capture: true })
+        colBand.addEventListener("dblclick", colDbl)
+        rowBand.addEventListener("dblclick", rowDbl)
+        colBand.addEventListener("lostpointercapture", onLostPointerCapture)
+        rowBand.addEventListener("lostpointercapture", onLostPointerCapture)
+        return () => {
+            colBand.removeEventListener("pointerdown", colDown, { capture: true })
+            rowBand.removeEventListener("pointerdown", rowDown, { capture: true })
+            colBand.removeEventListener("dblclick", colDbl)
+            rowBand.removeEventListener("dblclick", rowDbl)
+            colBand.removeEventListener("lostpointercapture", onLostPointerCapture)
+            rowBand.removeEventListener("lostpointercapture", onLostPointerCapture)
+            cleanupDrag()
+        }
+    }, [enabled, colBandRef, rowBandRef, isOwnPointer, cleanupDrag, commitResize, applyEntries, collectTargets, autofitColumns])
+
+    return useMemo(
+        () => ({
+            isDragging: () => draggingRef.current,
+            // リサイズ / unhide は選択矩形を配送しない — 配送モードは常に加算
+            getDragMode: (): "add" | "subtract" | "point" => "add",
+            // ドラッグ中は何も書いていない — 中断 = 消灯のみ (サイズ不変。復元対象なし)
+            abortDrag: () => {
+                if (draggingRef.current) {
+                    cleanupDrag()
+                }
+            },
+            cancelDrag: cleanupDrag,
+        }),
+        [cleanupDrag],
+    )
+}