@aiquants/spreadsheet 0.8.0

package/src/selection/selectionState.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Pure selection reducers (Excel semantics core — §6.4.2).
+ * Identity-preservation contract: every reducer returns the INPUT state object when the result
+ * is equivalent — the §6.9-1 setSelection wrapper's Object.is bail depends on it (breaking it
+ * double-fires onSelectionChange on a no-move click). Documented exception: subtract case (c)
+ * REBUILDS the pressCell 1x1, so an equivalent result there is a fresh object — the wrapper's
+ * structural bail absorbs it.
+ *
+ * 選択の純関数 reducer (Excel 意味論の中核 — §6.4.2)。identity 保存契約: 結果が入力と等価なら
+ * 入力 state をそのまま返す (setSelection ラッパーの Object.is bail の根拠)。明文例外: subtract
+ * の (c) は pressCell 1×1 を再構築するため等価でも新オブジェクト — ラッパーの構造 bail が受ける。
+ */
+
+import { type CellCoord, type CellRange, coordEquals, makeRange, rangeContains, type SpreadsheetDirection } from "../model/cellCoord.ts"
+
+/** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
+export type SelectionState = {
+    /** Non-contiguous range list; the tail is the "current range". / 非連続選択のレンジ列 (末尾が現在レンジ)。 */
+    ranges: readonly CellRange[]
+    /** Drag / Shift-extend origin. / ドラッグ / Shift 拡張の起点。 */
+    anchor: CellCoord
+    /** Active cell; never moved by extend operations (Excel semantics). / アクティブセル (拡張で不動)。 */
+    active: CellCoord
+}
+
+/** Press modifiers (extend = Shift, append = Ctrl/Cmd). / 押下修飾。 */
+export type SelectionModifiers = { extend: boolean; append: boolean }
+
+/** Structural equality of two ranges. / 2 レンジの構造等価 (identity 短絡の述語)。 */
+const rangeEquals = (a: CellRange, b: CellRange): boolean => a.startRow === b.startRow && a.startCol === b.startCol && a.endRow === b.endRow && a.endCol === b.endCol
+
+/**
+ * Structural equality of two selection states — the §6.9-1 wrapper's bail predicate for
+ * CONSTRUCTED states (Ctrl+A / corner / header composition build fresh objects, so the
+ * reducers' identity contract alone cannot suppress equivalent re-fires).
+ * 2 選択状態の構造等価 — 構築系 state (Ctrl+A / コーナー / ヘッダー合成) の等価再発火を
+ * ラッパー側で抑止する述語。
+ */
+export const selectionStateEquals = (a: SelectionState, b: SelectionState): boolean => a.ranges.length === b.ranges.length && a.ranges.every((range, i) => rangeEquals(range, b.ranges[i])) && coordEquals(a.anchor, b.anchor) && coordEquals(a.active, b.active)
+
+/** Replaces the tail range, preserving identity when unchanged. / 現在レンジのみ置換 (等価なら入力を返す)。 */
+const replaceCurrentRange = (state: SelectionState, next: CellRange): SelectionState => {
+    // identity 保存契約 (冒頭): 無変化なら新オブジェクトを作らない — §6.9-1 の Object.is bail の根拠
+    const current = state.ranges[state.ranges.length - 1]
+    if (rangeEquals(current, next)) {
+        return state
+    }
+    return { ...state, ranges: [...state.ranges.slice(0, -1), next] }
+}
+
+/** Press reducer (click / keyboard reset move). / 押下 reducer (クリック / キーボード reset 移動)。 */
+export const reduceSelectionPress = (state: SelectionState, cell: CellCoord, mods: SelectionModifiers): SelectionState => {
+    if (mods.extend) {
+        // Shift: anchor と active を維持し、現在レンジだけ置換 (Shift+Ctrl 同時は extend 優先 — Excel 同等)。
+        // extend reducer へ委譲 — 取り残しクランプを press 経路にも適用し、Shift+click の過渡発火でも
+        // active レンジ外の state を consumer へ流さない (R12 correctness の過渡残滓の封じ)
+        return reduceSelectionExtend(state, cell)
+    }
+    if (mods.append) {
+        return { ranges: [...state.ranges, makeRange(cell, cell)], anchor: cell, active: cell }
+    }
+    // 既に「そのセルだけの 1×1 選択」なら入力をそのまま返す (identity 保存 — 同一セル再クリックで発火しない)
+    if (state.ranges.length === 1 && coordEquals(state.anchor, cell) && coordEquals(state.active, cell) && rangeEquals(state.ranges[0], makeRange(cell, cell))) {
+        return state
+    }
+    return { ranges: [makeRange(cell, cell)], anchor: cell, active: cell }
+}
+
+/** Clamps a coordinate into a range. / 座標をレンジ内へクランプする補助。 */
+const clampIntoRange = (cell: CellCoord, range: CellRange): CellCoord => ({
+    row: Math.min(Math.max(cell.row, range.startRow), range.endRow),
+    col: Math.min(Math.max(cell.col, range.startCol), range.endCol),
+})
+
+/**
+ * Extend reducer (drag confirm / Shift+Arrow); active is immobile EXCEPT the stranded-active
+ * clamp: when a shrinking extend leaves active outside EVERY range (v0.2 invariant: active
+ * lives in SOME range, not necessarily the tail — multi-range cycling / subtraction moved it),
+ * active is clamped back into the tail range (Sheets-style — a documented deviation from the
+ * §6.6.2-3 immobility rule).
+ * 拡張 reducer (active 原則不動)。例外は取り残しクランプ — active が**どのレンジにも**含まれ
+ * なくなった場合のみ (v0.2 不変条件: active は必ずいずれかのレンジ内 — 末尾とは限らない)、
+ * 末尾レンジ内へクランプする (Sheets 準拠の文書化逸脱)。
+ */
+export const reduceSelectionExtend = (state: SelectionState, cell: CellCoord): SelectionState => {
+    const next = replaceCurrentRange(state, makeRange(state.anchor, cell))
+    if (next.ranges.some((range) => rangeContains(range, next.active))) {
+        return next // identity 保存契約はここで維持 (無変化 + active がいずれかのレンジ内なら入力をそのまま返す)
+    }
+    return { ...next, active: clampIntoRange(next.active, next.ranges[next.ranges.length - 1]) }
+}
+
+/**
+ * Subtracts a rectangle from every intersecting range (Ctrl+click / Ctrl+drag deselect —
+ * §3.1). Each intersecting range decomposes into at most 4 disjoint bands (top / bottom
+ * full-width, left / right only on the vertically overlapping rows), expanded in place of the
+ * original. Re-anchoring restores both invariants for EVERY case: (a) active survives — the
+ * first range containing it is extracted to the array tail and anchor := active; (b) active
+ * removed — anchor and active move to the top-left of the survivor array's tail range
+ * (fragment or untouched alike — always defined); (c) nothing survives — a 1x1 at pressCell.
+ * Zero intersection returns the input state (identity). Case (c) may REBUILD a structurally
+ * equal state — the documented exception to the identity contract; the §6.9-1 wrapper's
+ * structural bail absorbs the re-fire.
+ * 矩形減算 reducer (Ctrl+クリック / ドラッグの選択解除 — §3.1)。交差レンジは最大 4 の互いに
+ * 素な帯 (上下 = 全幅、左右 = 垂直重なり行のみ) へ分解し元位置へ展開する。再 anchor は全ケース
+ * で両不変条件を回復: (a) active 生存 → active を含む最初のレンジを末尾へ抜き出し anchor :=
+ * active。(b) active 除去 → 残存配列の末尾レンジ (フラグメントか否かを問わない) の左上へ移設。
+ * (c) 残存ゼロ → pressCell の 1×1。交差ゼロは入力をそのまま返す (identity 保存)。(c) の同値
+ * 再構築は identity 契約の明文例外 — ラッパーの構造 bail が無発火化する。
+ */
+export const reduceSelectionSubtract = (state: SelectionState, rect: CellRange, pressCell: CellCoord): SelectionState => {
+    let intersected = false
+    const survivors: CellRange[] = []
+    for (const range of state.ranges) {
+        // 交差なしのレンジは無変更でそのまま (identity 判定の分母)
+        if (rect.startRow > range.endRow || rect.endRow < range.startRow || rect.startCol > range.endCol || rect.endCol < range.startCol) {
+            survivors.push(range)
+            continue
+        }
+        intersected = true
+        // 帯分割 (重複なし — 生成順は上 → 下 → 左 → 右。負スパン帯は生成しない §3.1-1)
+        if (rect.startRow > range.startRow) {
+            survivors.push(makeRange({ row: range.startRow, col: range.startCol }, { row: rect.startRow - 1, col: range.endCol }))
+        }
+        if (rect.endRow < range.endRow) {
+            survivors.push(makeRange({ row: rect.endRow + 1, col: range.startCol }, { row: range.endRow, col: range.endCol }))
+        }
+        // 左右帯の行スパン = rect と元レンジの垂直重なり行のみ (上下帯との重複を作らない)
+        const midStart = Math.max(range.startRow, rect.startRow)
+        const midEnd = Math.min(range.endRow, rect.endRow)
+        if (rect.startCol > range.startCol) {
+            survivors.push(makeRange({ row: midStart, col: range.startCol }, { row: midEnd, col: rect.startCol - 1 }))
+        }
+        if (rect.endCol < range.endCol) {
+            survivors.push(makeRange({ row: midStart, col: rect.endCol + 1 }, { row: midEnd, col: range.endCol }))
+        }
+    }
+    if (!intersected) {
+        return state // identity 保存 (全レンジと交差ゼロ)
+    }
+    if (survivors.length === 0) {
+        // (c) 残存ゼロ → 押下セルの 1×1 (空選択の不可能性を維持)
+        return { ranges: [makeRange(pressCell, pressCell)], anchor: pressCell, active: pressCell }
+    }
+    const activeIndex = survivors.findIndex((range) => rangeContains(range, state.active))
+    if (activeIndex >= 0) {
+        // (a) active 生存 → 所属レンジ (先頭一致) を末尾へ抜き出し anchor := active
+        //     (「anchor = 末尾レンジ内」「active = いずれかのレンジ内」を同時回復。巡回順の
+        //      再順序化は §10 逸脱表の意図仕様)
+        const [containing] = survivors.splice(activeIndex, 1)
+        survivors.push(containing)
+        return { ranges: survivors, anchor: state.active, active: state.active }
+    }
+    // (b) active 除去 → 残存配列の末尾レンジ左上へ anchor / active を移設 (末尾は移動不要)
+    const topLeft: CellCoord = { row: survivors[survivors.length - 1].startRow, col: survivors[survivors.length - 1].startCol }
+    return { ranges: survivors, anchor: topLeft, active: topLeft }
+}
+
+/**
+ * One in-range cycle step at a (rangeIndex, cell) position: row-major for left/right,
+ * column-major for up/down; leaving the range's terminal cell transfers to the ADJACENT range
+ * (right/down = next range's top-left, left/up = previous range's bottom-right, circular).
+ * Single-range input reproduces the v0.1 same-range wrap exactly (adjacent = itself).
+ * (rangeIndex, cell) 位置の巡回 1 歩。レンジ終端セルからの離脱は隣接レンジの入口へ (right /
+ * down = 次レンジ左上、left / up = 前レンジ右下。環状)。単一レンジでは v0.1 の同レンジ
+ * 折り返しと完全一致 (隣接 = 自分自身)。
+ */
+const cycleStep = (ranges: readonly CellRange[], rangeIndex: number, cell: CellCoord, direction: SpreadsheetDirection): { rangeIndex: number; cell: CellCoord } => {
+    const range = ranges[rangeIndex]
+    if (direction === "right") {
+        if (cell.col < range.endCol) {
+            return { rangeIndex, cell: { row: cell.row, col: cell.col + 1 } }
+        }
+        if (cell.row < range.endRow) {
+            return { rangeIndex, cell: { row: cell.row + 1, col: range.startCol } } // 行末 → 次行の先頭
+        }
+    } else if (direction === "left") {
+        if (cell.col > range.startCol) {
+            return { rangeIndex, cell: { row: cell.row, col: cell.col - 1 } }
+        }
+        if (cell.row > range.startRow) {
+            return { rangeIndex, cell: { row: cell.row - 1, col: range.endCol } }
+        }
+    } else if (direction === "down") {
+        if (cell.row < range.endRow) {
+            return { rangeIndex, cell: { row: cell.row + 1, col: cell.col } }
+        }
+        if (cell.col < range.endCol) {
+            return { rangeIndex, cell: { row: range.startRow, col: cell.col + 1 } } // 列末 → 次列の上端
+        }
+    } else {
+        if (cell.row > range.startRow) {
+            return { rangeIndex, cell: { row: cell.row - 1, col: cell.col } }
+        }
+        if (cell.col > range.startCol) {
+            return { rangeIndex, cell: { row: range.endRow, col: cell.col - 1 } }
+        }
+    }
+    // レンジ終端 → 隣接レンジの入口 (環状)
+    if (direction === "right" || direction === "down") {
+        const nextIndex = (rangeIndex + 1) % ranges.length
+        const entry = ranges[nextIndex]
+        return { rangeIndex: nextIndex, cell: { row: entry.startRow, col: entry.startCol } }
+    }
+    const prevIndex = (rangeIndex - 1 + ranges.length) % ranges.length
+    const entry = ranges[prevIndex]
+    return { rangeIndex: prevIndex, cell: { row: entry.endRow, col: entry.endCol } }
+}
+
+/**
+ * Cycles the active cell across ALL ranges (the ONE sanctioned exception to the
+ * active-immobility rule — Tab/Enter data-entry loop). active's home range resolves
+ * statelessly to the FIRST range containing it; range edges transfer to the adjacent range's
+ * entrance. Overlap-skip rule: a landing whose coordinate equals the current active keeps
+ * advancing until the coordinate changes; a full circle back to the start position returns
+ * the input state (identity — the caller falls through to a reset move). Active outside every
+ * range is unreachable under the invariant and throws (No-Fallback: no silent tail rescue).
+ * Tab / Enter による全レンジ横断の active 巡回 (active 不動則の唯一の正規例外)。所属レンジは
+ * 先頭一致で stateless に解決し、レンジ終端は隣接レンジの入口へ乗り継ぐ。重なりスキップ:
+ * 着地座標が現在の active と同一なら座標が変わるまで前進し、開始位置へ全周したら入力 state を
+ * 返す (identity — 呼び出し側が reset へフォールスルー)。active がどのレンジにも属さない状態は
+ * 不変条件により unreachable — 発生時は throw (No-Fallback: 末尾レンジへの無音救済を発明しない)。
+ */
+export const reduceActiveCycle = (state: SelectionState, direction: SpreadsheetDirection): SelectionState => {
+    const startIndex = state.ranges.findIndex((range) => rangeContains(range, state.active))
+    if (startIndex === -1) {
+        throw new RangeError("[spreadsheet] reduceActiveCycle requires active inside some range (invariant violation)")
+    }
+    let position = { rangeIndex: startIndex, cell: state.active }
+    // 座標が変わるまで前進 (重なりレンジの同一座標入口をスキップ — §3.4-3)。ループ内では座標は
+    // 常に active と同一のため、開始位置 (rangeIndex) への回帰 = 全周 = identity
+    do {
+        position = cycleStep(state.ranges, position.rangeIndex, position.cell, direction)
+        if (!coordEquals(position.cell, state.active)) {
+            return { ...state, active: position.cell }
+        }
+    } while (position.rangeIndex !== startIndex)
+    return state // 全周して active 自身のみ (単一 1×1 / 重複同一レンジ群) — identity 保存
+}

package/src/selection/useAutoScroller.ts

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Edge-zone rAF auto-scroller for drag selection (§6.4.4). Driven by the
+ * selection engine via start/stop; hit tests use the 2-axis scrollBy synchronous return
+ * (freshness hierarchy §7-4: scrollBy return > getScrollPosition() — the store carries no
+ * positions since v0.4).
+ *
+ * ドラッグ選択の端ゾーン rAF オートスクロール (§6.4.4)。エンジンが start/stop で駆動し、
+ * ヒットテストは 2 軸 scrollBy の同期返り値を使う (鮮度序列 §7-4: scrollBy 返り値 >
+ * getScrollPosition — v0.4 からストアは位置を運ばない)。
+ */
+
+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, CellRange } from "../model/cellCoord.ts"
+import { clampCoord } from "../model/cellCoord.ts"
+import { viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
+
+/** Edge zone size in px. / 端ゾーン幅 (px)。 */
+const EDGE_ZONE = 24
+/** Max scroll speed in px per frame. / フレームあたり最大速度 (px)。 */
+const MAX_SPEED = 32
+
+/**
+ * Arming distance for edge auto-scroll (the fill machine's FILL_ARM_THRESHOLD twin — R5 fix):
+ * real clicks carry 1-3px jitter and coordinate-identical capture echoes, so a single move
+ * event must not arm the scroller (an edge-zone click would drain at 32px/frame). Only >= this
+ * cumulative movement from the press point arms.
+ * 端オートスクロールの武装距離 (fill 機械 FILL_ARM_THRESHOLD の双子 — R5 是正)。実クリックは
+ * 1〜3px のジッタと座標同値のキャプチャエコーを含むため、move 1 発では武装させない (端ゾーンの
+ * クリックが 32px/frame のドレインに化ける)。押下点から累計この距離以上の実移動のみ武装。
+ */
+export const SCROLLER_ARM_THRESHOLD = 4
+
+/** Start context supplied by the engine per drag. / エンジンがドラッグ毎に渡す開始コンテキスト。 */
+export type AutoScrollContext = {
+    /** Live pointer reader (a stable closure over the ref the engine updates per pointermove). / エンジンが pointermove ごとに更新する ref を読む安定クロージャ。 */
+    getPointerPosition: () => { clientX: number; clientY: number }
+    /**
+     * Hover cell to drag-rect range (the single construction point). Cell drags build
+     * anchor-to-hover; header drags promote to the §6.8-1 axis-full span — writing a raw
+     * anchor-to-hover here would overwrite the full-span rect with a non-span rect every tick
+     * during header drags.
+     * hover セル → ドラッグ矩形レンジの構築 (単一の構築点)。セルドラッグは anchor→hover、
+     * ヘッダードラッグは片軸全域スパンへ昇格 (素の anchor→hover 直書きは毎 tick の非スパン上書き)。
+     */
+    buildRange: (hover: CellCoord) => CellRange
+    /**
+     * Drag-anchor column for the frozen home-territory rule (v0.5 R5 fix): when the anchor is
+     * a frozen column AND the pointer sits inside the frozen band, the band-based left zone
+     * does NOT drive — operating within the frozen pane must not scroll the band (Excel-like).
+     * Omit for vertical-only drags.
+     * 凍結ホームテリトリー規則 (v0.5 R5 是正) 用のドラッグアンカー列。アンカーが凍結列で
+     * ポインタも凍結帯内なら帯基準左ゾーンは駆動しない — 凍結ペイン内の操作は可動帯を
+     * スクロールさせない (Excel 同型)。縦専用ドラッグでは省略。
+     */
+    anchorCol?: number
+    /**
+     * Drag-anchor row for the vertical frozen home-territory rule (row twin of anchorCol — v0.6):
+     * anchor frozen AND pointer inside the frozen band suppresses the band-based top zone.
+     * 縦の凍結ホームテリトリー規則用のドラッグアンカー行 (anchorCol の行双子 — v0.6)。アンカーが
+     * 凍結行でポインタも凍結帯内なら帯基準上ゾーンは駆動しない。
+     */
+    anchorRow?: number
+}
+
+type UseAutoScrollerParams = {
+    /** 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>
+    handleRef: RefObject<VirtualGridHandle | null>
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    bodyRef: RefObject<HTMLElement | null>
+    onDragFrame: (range: CellRange | null) => void
+    /** Axis restriction (header drags drive a single axis — §6.8). / 軸制限 (ヘッダードラッグは片軸のみ駆動)。 */
+    axis?: "both" | "x" | "y"
+}
+
+/** Return surface consumed by the engine. / エンジンが消費する戻り面。 */
+export type AutoScroller = {
+    start: (ctx: AutoScrollContext) => void
+    stop: () => void
+}
+
+/**
+ * Builds the drag auto-scroller (rAF loop active only while dragging).
+ * ドラッグ中のみ稼働する rAF ループのオートスクローラーを構築。
+ *
+ * 既知特性: 速度は rAF 結合のため 120Hz 表示では 60Hz の 2 倍速になる (Excel も同型の
+ * フレーム結合 — 時間正規化はドラッグ体感を粘らせるため v0.1 では採らない)。
+ */
+export const useAutoScroller = ({ handleRef, rowAxis, colAxis, bodyRef, onDragFrame, axis = "both", zoomRef }: UseAutoScrollerParams): AutoScroller => {
+    const rafIdRef = useRef<number | null>(null)
+    const contextRef = useRef<AutoScrollContext | null>(null)
+    /** Last tick's hover (suppresses identical rewrites on stationary no-scroll ticks). / 直近 tick の hover (静止 + 無スクロール tick の同値再描画を抑止)。 */
+    const lastHoverRef = useRef<CellCoord | null>(null)
+    // bodyRect はドラッグ開始時にエンジンが計測したものと同条件で 1 回だけ読む (§6.4.3-3 の
+    // レイアウト読み規律 — body の画面位置はドラッグ中不変)
+    const bodyRectRef = useRef<DOMRect | null>(null)
+
+    /** Idempotent stop (§6.4.4-3). / 冪等な停止関数。 */
+    const stop = useCallback(() => {
+        if (rafIdRef.current !== null) {
+            cancelAnimationFrame(rafIdRef.current)
+            rafIdRef.current = null
+        }
+        contextRef.current = null
+        bodyRectRef.current = null
+        lastHoverRef.current = null
+    }, [])
+
+    /** One edge-scroll + re-hit-test frame. / 端スクロール + 再ヒットテストの 1 フレーム。 */
+    const tick = useCallback(() => {
+        const context = contextRef.current
+        const handle = handleRef.current
+        const rect = bodyRectRef.current
+        if (context === null || handle === null || rect === null) {
+            rafIdRef.current = null
+            return
+        }
+        const { clientX, clientY } = context.getPointerPosition()
+        // ズーム境界 (v0.3): ポインタ / rect は視覚 px — ペイン局所の論理 px へ 1 回だけ変換し、
+        // 端ゾーン幅・速度・ヒットテストを全て論理系で統一する (EDGE_ZONE / MAX_SPEED は論理 px)
+        const z = zoomRef.current
+        const px = (clientX - rect.left) / z
+        const py = (clientY - rect.top) / z
+        // ペイン寸法はセルビューポート (getViewportSize — バー帯除外の論理 px)。body rect は
+        // v0.4 からバー帯 2 本を内包するため、rect 寸法だと下端ゾーンが横バー帯へ 12px 食い込む。
+        // コンテンツ原点は body 左上と一致 (バーは右 / 下) なので px / py はそのまま比較できる
+        const viewport = handle.getViewportSize()
+        const paneW = viewport.width
+        const paneH = viewport.height
+        // 未計測 (幅高 0 以下) はドラッグ成立前の過渡 — 端判定せず次フレームへ (代替値は使わない)
+        if (paneW <= 0 || paneH <= 0) {
+            rafIdRef.current = requestAnimationFrame(tick)
+            return
+        }
+        // 食い込み深さの線形関数 (depth / 24 * 32、最大 32)。ceil は意図的な微逸脱 (§6.4.4-1 は素の
+        // 線形): 端に 1px でも触れたら必ず 1px/frame 以上動く下限を作り、浮動小数の 0 埋めで
+        // 「触れているのに進まない」帯を消す
+        const speedFor = (depth: number): number => Math.min(MAX_SPEED, Math.ceil((depth / EDGE_ZONE) * MAX_SPEED))
+        let dy = 0
+        let dx = 0
+        if (axis !== "x") {
+            // 上端ゾーンは帯基準 (v0.6 計画 §3 — 横の左端ゾーンと対称): スクロール帯の上端 = H_F。
+            // 下端優先 + 凍結ホームテリトリー (アンカー凍結行 × ポインタ帯内は駆動しない、H_F = 0 除外)
+            const frozenV = handle.getFrozenSize()
+            if (py > paneH - EDGE_ZONE) {
+                dy = speedFor(py - (paneH - EDGE_ZONE))
+            } else if (py < frozenV.height + EDGE_ZONE) {
+                const anchorFrozenRow = context.anchorRow !== undefined && context.anchorRow < frozenV.rows
+                if (!(anchorFrozenRow && frozenV.height > 0 && py < frozenV.height)) {
+                    dy = -speedFor(frozenV.height + EDGE_ZONE - py)
+                }
+            }
+        }
+        if (axis !== "y") {
+            // 左端ゾーンは帯基準 (v0.5 計画 §3-6): スクロール帯の左端 = W_F。スクロール帯アンカーの
+            // ドラッグは凍結帯上の保持でも左スクロールが継続する (Excel 同型 — 帯を跨いだ引き寄せ)。
+            // 判定は右端優先 (R2 是正): 帯幅 < 2×EDGE_ZONE で両ゾーンが重なると左優先は右端保持の
+            // ドラッグを逆走させる — 重なりは右端が勝つ。凍結ホームテリトリー (R5 是正): アンカーが
+            // 凍結列でポインタも凍結帯内なら駆動しない — 凍結ペイン内の選択操作が可動帯を勝手に
+            // 左スクロールさせない (帯外 [W_F, W_F+EDGE_ZONE) の戻りドラッグは従来どおり駆動)
+            const frozen = handle.getFrozenSize()
+            if (px > paneW - EDGE_ZONE) {
+                dx = speedFor(px - (paneW - EDGE_ZONE))
+            } else if (px < frozen.width + EDGE_ZONE) {
+                // W_F = 0 (凍結列が全て非表示) は可視の凍結帯が存在しない — 負 px を帯内と
+                // 誤認して抑止しない (R5 是正)
+                const anchorFrozen = context.anchorCol !== undefined && context.anchorCol < frozen.cols
+                if (!(anchorFrozen && frozen.width > 0 && px < frozen.width)) {
+                    dx = -speedFor(frozen.width + EDGE_ZONE - px)
+                }
+            }
+        }
+        // 両軸とも scrollBy のクランプ後同期返り値を採用 (§7-4 の鮮度序列 — 行側の
+        // `const vy = handle.scrollBy(dy)` パターンの 2 軸同文)。0 デルタ軸は動かさず最新値のみ読む
+        const applied = dx !== 0 || dy !== 0 ? handle.scrollBy({ x: dx !== 0 ? dx : undefined, y: dy !== 0 ? dy : undefined }) : handle.getScrollPosition()
+        const vy = applied.y
+        const hx = applied.x
+        // スクロール後にその場でヒットテスト再実行 → onDragFrame (ポインタ静止でも選択が伸びる)。
+        // レンジ構築は context.buildRange の 1 点 (ヘッダードラッグの片軸全域昇格を尊重 — §6.8-1)。
+        // 静止 + 無スクロール + hover 同値の tick は書き込みをスキップ (同値スタイルの毎フレーム
+        // 再書き込みを抑止 — スクロール追随の再配置は repaintOverlay 側が担う)
+        if (vy >= 0 && hx >= 0 && rowAxis.totalSize() > 0 && colAxis.totalSize() > 0) {
+            // 行 / 列とも凍結パーティション逆写像 (v0.6 / v0.5 計画 §2)
+            const frozenHover = handle.getFrozenSize()
+            const hover = clampCoord({ row: viewportYToRow(rowAxis, py, vy, frozenHover.height), col: viewportXToCol(colAxis, px, hx, frozenHover.width) }, rowAxis.count, colAxis.count)
+            const last = lastHoverRef.current
+            if (dy !== 0 || dx !== 0 || last === null || last.row !== hover.row || last.col !== hover.col) {
+                lastHoverRef.current = hover
+                onDragFrame(context.buildRange(hover))
+            }
+        }
+        rafIdRef.current = requestAnimationFrame(tick)
+    }, [handleRef, rowAxis, colAxis, axis, onDragFrame])
+
+    const start = useCallback(
+        (ctx: AutoScrollContext) => {
+            stop()
+            contextRef.current = ctx
+            bodyRectRef.current = bodyRef.current?.getBoundingClientRect() ?? null
+            rafIdRef.current = requestAnimationFrame(tick)
+        },
+        [stop, tick, bodyRef],
+    )
+
+    // 停止条件: visibilitychange (hidden) とアンマウント (§6.4.4-3)
+    useEffect(() => {
+        const onVisibilityChange = () => {
+            if (document.visibilityState === "hidden") {
+                stop()
+            }
+        }
+        document.addEventListener("visibilitychange", onVisibilityChange)
+        return () => {
+            document.removeEventListener("visibilitychange", onVisibilityChange)
+            stop()
+        }
+    }, [stop])
+
+    // 戻り値は memo 必須: 毎レンダー新オブジェクトだと消費側 effect (エンジン / ヘッダー機械) の
+    // deps が毎回変わり、押下の setState 再レンダーで cleanupDrag が走ってドラッグが即死する
+    // (E2E で実測した欠陥クラス)
+    return useMemo(() => ({ start, stop }), [start, stop])
+}