@aiquants/spreadsheet 0.8.0

package/src/overlay/useFillHandle.ts

@@ -0,0 +1,432 @@
+/**
+ * @fileoverview Fill-handle machine (§8 PT-2 — copy fill only). Wires ONE wire-once
+ * pointerdown onto the resident handle node (pointer-events exception #2). The press sets the
+ * machine's OWN dragging flag BEFORE the mandatory press repaint (the §8.1 visibility freeze
+ * must be engaged when the repaint evaluates, or display:none kills the capture). The drag is
+ * box-based (v0.3 diagonal fill: box = bounding rect of source ∪ hover — single-axis and
+ * diagonal drags share ONE derivation, an inward hover collapses to no extension) and paints
+ * only the dashed preview box through the overlay writer; edge scrolling starts BOTH
+ * construction-time axis-fixed autoscrollers once armed (each ticks only in its own edge
+ * zone — no axis selection, no flip). The confirmed box is the LAST PREVIEWED box (source-containing bounding rect; no re-hit-test at up): one
+ * commitEdits of expandFill, selection updated to the merged rect ONLY on success. A
+ * zero-extension up is a no-write cleanup (no bumpEdit / clip discard). The expansion carries
+ * what fillDown / fillRight carry (v0.8, spec 08 §4 fill row — `readFillSource` /
+ * `fillSourceEdit`): the formula source shifted per target when `getCellFormula` is declared,
+ * plus every declared aspect (format / validation / hyperlink / note), comments never; a v0.7
+ * adapter yields exactly `{ row, col, text }`.
+ *
+ * fill ハンドル機械 (§8 PT-2 — copy fill のみ)。常設ハンドルノードへ wire-once の pointerdown
+ * を 1 本。press は義務 repaint より先に自機フラグをセット (§8.1 の可視凍結が評価前に成立して
+ * いないと display:none が capture を殺す)。ドラッグはボックス方式 (v0.3 の斜め
+ * フィル: ボックス = ソース ∪ hover のバウンディング矩形 — 単軸も斜めも同一導出、内向き hover
+ * は拡張なしへ収縮) で破線プレビューボックスだけを overlay writer 経由で描く。端スクロールは
+ * 武装時に構築時軸固定の 2 インスタンスを**両方**起動 (各自の端ゾーンでのみ tick — 軸選択も
+ * 反転もなし)。
+ * 確定ボックス = 最終プレビューボックス (up の再ヒットテストなし — ソース包含の合併矩形)。
+ * expandFill を commitEdits 1 回、選択
+ * 更新 (合併矩形) は成功時のみ。拡張ゼロの up は無書込 cleanup (bumpEdit / クリップ破棄を
+ * 発火させない)。展開が運ぶものは fillDown / fillRight と同じ (v0.8、分冊 08 §4 の fill 行 —
+ * `readFillSource` / `fillSourceEdit`): `getCellFormula` 宣言時は対象毎に相対シフトした数式ソース、
+ * 宣言済み側面 (format / validation / hyperlink / note) の全部、comments は決して運ばず、v0.7
+ * アダプタは `{ row, col, text }` ちょうど。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import { estimateFillCellCount, expandFill, fillSourceEdit, readFillSource } from "../clipboard/tiling.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellCoord, type CellRange, clampCoord, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import type { CellEdit, EditRejection, SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
+import type { SelectionState } from "../selection/selectionState.ts"
+import type { AutoScroller } from "../selection/useAutoScroller.ts"
+import type { SelectionEngine } from "../selection/useSelectionEngine.ts"
+
+/**
+ * Drag-arm threshold in px (R2(B) 実証欠陥の閉塞): NO box is built until the pointer has
+ * moved this far from the press point. Without it, a coordinate-identical capture echo (or
+ * 1-3px click jitter) reaches the preview rAF, and because the handle hitbox overhangs the
+ * corner into the NEXT track, the press point itself hit-tests outside the source — a
+ * zero-movement up would silently WRITE a 1-track fill. Excel writes nothing below the drag
+ * threshold.
+ * ドラッグ開始閾値 (px — R2(B) 実証欠陥の閉塞)。押下点からこの距離を動くまでボックスを構築しない。
+ * これが無いと座標同値のキャプチャエコー (や 1〜3px のクリックジッタ) がプレビュー rAF に届き、
+ * ハンドル hit 面が隅を次トラックへ張り出しているため押下点自体が ソース外に解決 — 無移動の
+ * up が 1 トラック fill を無言で書く。Excel はドラッグ閾値未満で何も書かない。
+ */
+const FILL_ARM_THRESHOLD = 4
+
+type UseFillHandleParams = {
+    /** 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 (§11 enableFillHandle opt-out / empty grid). / 不活性ゲート (§11 の opt-out / 空グリッド)。 */
+    enabled: boolean
+    /** The resident handle node (overlay-owned). / 常設ハンドルノード (overlay 所有)。 */
+    handleNodeRef: RefObject<HTMLElement | null>
+    bodyRef: RefObject<HTMLElement | null>
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    handleRef: RefObject<VirtualGridHandle | null>
+    getSelection: () => SelectionState
+    setSelection: (next: SelectionState) => void
+    focusSink: () => void
+    adapter: SpreadsheetDataAdapter
+    /** The §6.9-2 write funnel: the transaction id on success (the edit version is bumped + the clip commit-discarded), null when the adapter rejected — the selection expands only on an id. / §6.9-2 の書込漏斗: 成功はトランザクション id (bumpEdit + クリップの commit 破棄)、アダプタ拒否は null — 選択の拡大は id のときだけ。 */
+    commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    maxOperationCells: number
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    /** Preview writer relay (overlay-owned positioner + liveFillPreviewRef). / プレビュー writer リレー。 */
+    writeFillPreview: (range: CellRange | null) => void
+    /** §8.2 repaint edges (press after flag + cleanup end). / §8.2 の repaint エッジ。 */
+    repaintOverlay: () => void
+    /** Axis-fixed edge scrollers (writer + axis frozen at construction — §8.2). / 軸固定エッジスクローラー 2 台。 */
+    xAutoScroller: AutoScroller
+    yAutoScroller: AutoScroller
+}
+
+/**
+ * Wires the fill machine onto the handle node; returns the §7.4 composite surface.
+ * ハンドルノードへ fill 機械を結線し、§7.4 の合成面を返す。
+ */
+export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const draggingRef = useRef(false)
+    /** Source range captured at press (the fill origin). / press 時に捕捉するソースレンジ。 */
+    const sourceRangeRef = useRef<CellRange | null>(null)
+    /** The LAST previewed fill BOX (source-containing bounding rect; null = no extension) — the §8.2 confirm truth. / 最終プレビューの fill ボックス (ソース包含の合併矩形。null = 拡張なし — §8.2 の確定真実)。 */
+    const liveBandRef = useRef<CellRange | null>(null)
+    const bodyRectRef = useRef<DOMRect | null>(null)
+    const pointerRef = useRef({ clientX: 0, clientY: 0 })
+    /** Press point for the arming arithmetic (dx/dy origin — §8.2). / 武装算術の押下点 (dx / dy の原点)。 */
+    const pressPointRef = useRef({ clientX: 0, clientY: 0 })
+    /** Armed once the pointer moved >= FILL_ARM_THRESHOLD from the press (box building enabled; stays armed). / 押下から閾値以上動いたら armed (ボックス構築の解禁 — 以後維持)。 */
+    const dragArmedRef = useRef(false)
+    /**
+     * Grab-offset normalization (R2(B) — the Excel drag-back-to-source-cancel contract): the
+     * press grabbed the HANDLE, whose hitbox straddles the corner boundary, so the raw press
+     * pixel hit-tests into the adjacent track and a return-to-press-point release could never
+     * collapse the box to the source (null). The offset re-anchors every hover hit test to "the pointer
+     * grabbed the corner's last inside pixel": effective = current − (press − (corner − 1)).
+     * grab オフセット正規化 (R2(B) — Excel の「ソースへ戻すと取り消し」契約)。押下はハンドル =
+     * 隅境界を跨ぐ hit 面を掴んでおり、生の押下 px は隣トラックに解決するため押下点へ戻した
+     * リリースがボックス null へ畳めない。オフセットで全 hover ヒットテストを「隅の内側最終 px を
+     * 掴んだ」座標系へ再アンカーする。
+     */
+    const grabOffsetRef = useRef({ dx: 0, dy: 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)
+    const moveRafRef = useRef<number | null>(null)
+    const windowListenersRef = useRef<{ move: (e: PointerEvent) => void; up: (e: PointerEvent) => void } | null>(null)
+    /**
+     * Whether an edge scroller is running (started on the FIRST genuine pointermove, NOT at
+     * press — a press-started tick would scroll/grow the box under a STATIONARY hold and the
+     * zero-movement up would silently WRITE a fill: the §8.2 zero-extension no-write pin is
+     * structurally bypassed by scroll-grown boxes. Excel never scrolls on a stationary handle
+     * hold. R1(B) 実証欠陥の閉塞).
+     * エッジスクローラー稼働中フラグ (起動は press でなく**最初の実 pointermove** — press 起動の
+     * tick は静止保持のままスクロールでボックスを育て、無移動 up が無言でデータを書く: §8.2 の
+     * 拡張ゼロ無書込ピンがスクロール成長ボックスで構造的に迂回される。Excel は静止保持でスクロール
+     * しない。R1(B) 実証欠陥の閉塞)。
+     */
+    const scrollerActiveRef = useRef(false)
+
+    const isOwnPointer = useCallback((event: PointerEvent): boolean => (capturedPointerRef.current !== null ? event.pointerId === capturedPointerRef.current : event.pointerType === "mouse"), [])
+
+    /** Engine-style hit test (press-cached rect + freshness hierarchy). / エンジン同型のヒットテスト (press 計測 rect + 鮮度序列)。 */
+    const hitTest = useCallback((clientX: number, clientY: number): CellCoord | null => {
+        const { handleRef, rowAxis, colAxis } = paramsRef.current
+        const handle = handleRef.current
+        const rect = bodyRectRef.current
+        if (handle === null || rect === null) {
+            return null
+        }
+        // 両軸ともハンドルの同期読み (§7-4 — fill プレビューの着地列がドラッグ中も最新 hx で決まる)
+        const { x: hx, y: vy } = handle.getScrollPosition()
+        if (vy < 0 || hx < 0 || rowAxis.totalSize() === 0 || colAxis.totalSize() === 0) {
+            return null
+        }
+        // ズーム境界 (v0.3): client 差分を z で 1 回だけ除算して論理 px へ。
+        // 列は凍結パーティション逆写像 (v0.5 計画 §2)
+        const z = paramsRef.current.zoomRef.current
+        const frozen = handle.getFrozenSize()
+        return clampCoord({ row: viewportYToRow(rowAxis, (clientY - rect.top) / z, vy, frozen.height), col: viewportXToCol(colAxis, (clientX - rect.left) / z, hx, frozen.width) }, rowAxis.count, colAxis.count)
+    }, [])
+
+    /**
+     * The single box/preview construction point shared by the move rAF and BOTH autoscroller
+     * ticks: the box is the bounding rect of source ∪ hover (v0.3 diagonal fill — one
+     * derivation for single-axis and diagonal drags), stored as the confirm truth
+     * (liveBandRef — box written ⇔ preview drawn, atomically in this closure) and returned as
+     * the preview rect. A hover resolving inside the source = no extension (§8.2).
+     * move rAF と両 tick が共有するボックス / プレビューの単一構築点。ボックス = ソース ∪
+     * hover のバウンディング矩形 (v0.3 の斜めフィル — 単軸も斜めも同一導出)。確定真実
+     * (liveBandRef — ボックスの記録とプレビュー描画はこのクロージャで原子的) を更新して
+     * プレビュー矩形を返す。ソース内向き hover は拡張なし (§8.2)。
+     */
+    const buildFillFrame = useCallback((hover: CellCoord): CellRange => {
+        const source = sourceRangeRef.current
+        if (source === null) {
+            return makeRange(hover, hover) // 構造的に不到達 (press で必ず捕捉) — 型充足のみ
+        }
+        // ボックス = ソース ∪ hover のバウンディング矩形 (v0.3 の斜めフィル — 単軸も斜めも同一
+        // 導出。hover がソース内へ解決する間はボックス = ソース = 拡張なし)
+        const box = makeRange({ row: Math.min(source.startRow, hover.row), col: Math.min(source.startCol, hover.col) }, { row: Math.max(source.endRow, hover.row), col: Math.max(source.endCol, hover.col) })
+        const extended = box.startRow !== source.startRow || box.endRow !== source.endRow || box.startCol !== source.startCol || box.endCol !== source.endCol
+        liveBandRef.current = extended ? box : null
+        return extended ? box : source
+    }, [])
+
+    /** Idempotent cleanup (§8.2 — preview off, both scrollers stopped, cleanup repaint edge). / 冪等な後始末。 */
+    const cleanupDrag = useCallback(() => {
+        const p = paramsRef.current
+        draggingRef.current = false
+        sourceRangeRef.current = null
+        liveBandRef.current = null
+        bodyRectRef.current = null
+        if (moveRafRef.current !== null) {
+            cancelAnimationFrame(moveRafRef.current)
+            moveRafRef.current = null
+        }
+        p.xAutoScroller.stop()
+        p.yAutoScroller.stop()
+        scrollerActiveRef.current = false
+        dragArmedRef.current = false
+        grabOffsetRef.current = { dx: 0, dy: 0 }
+        p.writeFillPreview(null)
+        const listeners = windowListenersRef.current
+        if (listeners !== null) {
+            window.removeEventListener("pointermove", listeners.move)
+            window.removeEventListener("pointerup", listeners.up)
+            windowListenersRef.current = null
+        }
+        const node = paramsRef.current.handleNodeRef.current
+        if (node !== null && capturedPointerRef.current !== null && node.hasPointerCapture?.(capturedPointerRef.current)) {
+            node.releasePointerCapture(capturedPointerRef.current)
+        }
+        capturedPointerRef.current = null
+        p.repaintOverlay()
+    }, [])
+
+    /** The up confirm: box = last preview; estimate gate; ONE commitEdits; selection on success. / up 確定 (最終プレビューボックス・見積ゲート・commitEdits 1 回・成功時のみ選択更新)。 */
+    const confirmFill = useCallback(() => {
+        const p = paramsRef.current
+        const source = sourceRangeRef.current
+        const box = liveBandRef.current
+        cleanupDrag()
+        if (source === null || box === null) {
+            // 拡張ゼロ (ハンドル単クリック / 内向き) は無書込 cleanup — 空 edits の commit は
+            // ラッパー経由で bumpEdit + クリップ破棄を発火してしまう (§8.2 の明文ピン)
+            return
+        }
+        // 上限検査は展開前かつソース読み出し前 (ADR-12 §8.3)。count = 領域 (ボックス − ソース) + ソース読み課金の和
+        const count = estimateFillCellCount(source, box)
+        if (count > p.maxOperationCells) {
+            p.onOperationRejected?.("fill", count, "limit")
+            return
+        }
+        // 展開は fillDown / fillRight と同じソース毎規則 (分冊 08 §4 の fill 行): 種 (数式ソースか正準
+        // 文字列) + 宣言済み側面を 1 回読み、対象毎に数式を相対シフト — v0.7 アダプタは { row, col, text } ちょうど
+        const edits = expandFill((row, col) => readFillSource(p.adapter, row, col), source, box, fillSourceEdit)
+        if (p.commitEdits(edits, { source: "fill" }) === null) {
+            return // 読み取り専用 adapter の throw (null) — 「埋まっていないセルへ選択だけ拡大」を作らない (§8.2)
+        }
+        // 選択更新はボックス 1 レンジ — ボックスはソースを構造的に包含する (buildFillFrame の
+        // 合併矩形 + assertFillBox の封鎖) ため v0.2 帯時代の min/max 合併算術は恒等で不要。
+        // anchor / active 不動 (両者はソース内 = ボックス内で両不変条件が自明に維持される)
+        const state = p.getSelection()
+        p.setSelection({ ranges: [box], anchor: state.anchor, active: state.active })
+    }, [cleanupDrag])
+
+    const { enabled, handleNodeRef } = params
+    useEffect(() => {
+        const node = handleNodeRef.current
+        if (!enabled || node === null) {
+            return
+        }
+
+        const onWindowPointerMove = (event: PointerEvent) => {
+            applyWindowPointerMove(event)
+            // chord 中の主ボタン解放 (R4 是正 — 解放検出の述語は選択機械と同型): 主ビットを失った own move を
+            // pointerup と同じ確定経路へ流す。確定ボックスは最終プレビュー (直前の rAF が描いた帯) — この move の
+            // 位置は反映しない (§8.2 の「up で再ヒットテストしない」規約と同一。R5 是正で明記)
+            if (draggingRef.current && isOwnPointer(event) && (pressButtonsRef.current & 1) !== 0 && (event.buttons & 1) === 0) {
+                confirmFill()
+            }
+        }
+
+        const applyWindowPointerMove = (event: PointerEvent) => {
+            if (!(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            const dx = Math.abs(event.clientX - pressPointRef.current.clientX)
+            const dy = Math.abs(event.clientY - pressPointRef.current.clientY)
+            // ドラッグ武装 (R2(B)): 押下点から閾値以上の実移動で解禁し、以後維持する。座標同値の
+            // 合成 move もジッタも武装させない — ボックス構築とスクローラーの両ドアを 1 述語で守る
+            if (!dragArmedRef.current && Math.max(dx, dy) >= FILL_ARM_THRESHOLD) {
+                dragArmedRef.current = true
+            }
+            if (!dragArmedRef.current) {
+                return
+            }
+            // エッジスクローラーは武装後に両軸とも起動する (v0.3 の斜めフィル — ボックスは hover
+            // 由来のため軸選択は不要。各スクローラーは自軸の端ゾーンでのみ tick する)。押下起動は
+            // 静止保持の無言書込に化ける — scrollerActiveRef の docstring 参照。tick の座標読みにも
+            // grab オフセットを適用する (ボックス構築系の単一正規化)
+            if (!scrollerActiveRef.current) {
+                const p = paramsRef.current
+                const context = {
+                    getPointerPosition: () => ({ clientX: pointerRef.current.clientX - grabOffsetRef.current.dx, clientY: pointerRef.current.clientY - grabOffsetRef.current.dy }),
+                    buildRange: buildFillFrame,
+                    // 凍結ホームテリトリー規則 (R5 是正): ソース隅列が凍結なら帯内保持で左駆動しない
+                    anchorCol: sourceRangeRef.current?.endCol,
+                    anchorRow: sourceRangeRef.current?.endRow,
+                }
+                p.xAutoScroller.start(context)
+                p.yAutoScroller.start(context)
+                scrollerActiveRef.current = true
+            }
+            // プレビューは rAF 合流の直書き (§8.2) — hover は grab 正規化座標で解決する
+            if (moveRafRef.current === null) {
+                moveRafRef.current = requestAnimationFrame(() => {
+                    moveRafRef.current = null
+                    if (!(draggingRef.current && dragArmedRef.current)) {
+                        return
+                    }
+                    const hover = hitTest(pointerRef.current.clientX - grabOffsetRef.current.dx, pointerRef.current.clientY - grabOffsetRef.current.dy)
+                    if (hover !== null) {
+                        paramsRef.current.writeFillPreview(buildFillFrame(hover))
+                    }
+                })
+            }
+        }
+
+        const onWindowPointerUp = (event: PointerEvent) => {
+            // 主ボタンのリリースのみ確定 (他機械と同じ閉塞)
+            if (event.button !== 0 || !(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            confirmFill()
+        }
+
+        const onPointerDown = (event: PointerEvent) => {
+            const p = paramsRef.current
+            if (event.pointerType !== "mouse") {
+                return
+            }
+            if (event.button !== 0) {
+                // 非主ボタン: 既定のフォーカス移動だけ止めて素通し (全押下面共通 — R2 是正)
+                event.preventDefault()
+                return
+            }
+            // 編集中 requestCommit ゲートは置かない (§8.2): ハンドルは編集中非表示で押下が構造的に
+            // 不到達 — 観測不能ガード禁止規律 (§8.1) に従い書かない
+            event.preventDefault()
+            event.stopPropagation()
+            p.focusSink()
+            const state = p.getSelection()
+            const source = state.ranges[state.ranges.length - 1]
+            sourceRangeRef.current = source
+            liveBandRef.current = null
+            dragArmedRef.current = false
+            // 押下時自己修復 (R6 是正 — セル / ヘッダー機械と同規約): 宙吊り fill ジェスチャが
+            // 残した両軸スクローラーと stale active フラグを毎押下で掃除する (旧 anchorCol
+            // コンテキストの生存遮断)
+            p.xAutoScroller.stop()
+            p.yAutoScroller.stop()
+            scrollerActiveRef.current = false
+            pressPointRef.current = { clientX: event.clientX, clientY: event.clientY }
+            pointerRef.current = pressPointRef.current
+            pressButtonsRef.current = event.buttons
+            // 自機フラグを同期セットしてから義務の press repaint (§8.1 — 凍結が成立した状態で
+            // 可視条件が評価される。順序を崩すと押下即 display:none → lostpointercapture 死)
+            draggingRef.current = true
+            p.repaintOverlay()
+            // rect 規律 (§8.2): fill 機械自身のヒットテスト rect は押下 1 回計測をジェスチャ共有
+            bodyRectRef.current = p.bodyRef.current?.getBoundingClientRect() ?? null
+            // grab オフセット (R2(B)): 押下 px を「隅の内側最終 px を掴んだ」座標系へ再アンカー
+            // (grabOffsetRef の docstring 参照)。rect / スクロール未計測時は素の座標 (オフセット 0)
+            const rect = bodyRectRef.current
+            const pressPosition = p.handleRef.current?.getScrollPosition() ?? { x: -1, y: -1 }
+            const pressVy = pressPosition.y
+            if (rect !== null && pressVy >= 0 && pressPosition.x >= 0) {
+                const hx = pressPosition.x
+                // ズーム境界 (v0.3): 論理オフセットは ×z で視覚 px へ写してから client と比較する
+                const zPress = p.zoomRef.current
+                // 隅の x は凍結パーティション順写像 (v0.5 計画 §2 — repaintOverlay のハンドル描画と
+                // 同式)。無条件 −hx だと凍結 endCol の押下で dx が hx·z ぶん膨らみ、以後の全ヒット
+                // テストが左へ hx ずれる (誤列への fill 確定 + 暴走左オートスクロール)
+                const pressFrozen = p.handleRef.current?.getFrozenSize() ?? { cols: 0, width: 0, rows: 0, height: 0 }
+                const cornerViewportX = colToViewportX(p.colAxis, source.endCol, hx, pressFrozen.cols) + p.colAxis.sizeOf(source.endCol)
+                // 隅 y も凍結パーティション順写像 (v0.6 — repaintOverlay のハンドル描画と同式)
+                const cornerViewportY = rowToViewportY(p.rowAxis, source.endRow, pressVy, pressFrozen.rows) + p.rowAxis.sizeOf(source.endRow)
+                // 内側 1px は論理 px の概念 (「隅の内側最終 px」) — 視覚 1px のままだと z < 1 で
+                // 1/z 論理 px に膨らみ、極小トラック (< 1/z px) では隣トラックへ再アンカーされて
+                // 押下点回帰キャンセルが 1 トラック fill に化ける。×zPress で論理 1px に固定。
+                // スクロール帯の隅が W_F との 1px 未満の隙間に立つ場合 (小数 hx で到達可能)、
+                // 内側 px が凍結帯へ潜って全ヒットテストが F−1 列へ解決する — 帯下限 W_F で
+                // クランプ (R2 是正。凍結 endCol と W_F = 0 はクランプ不要 — 後者は v0.4 恒等)
+                const insideRawX = cornerViewportX - 1
+                const insideViewportX = source.endCol >= pressFrozen.cols && pressFrozen.width > 0 ? Math.max(insideRawX, pressFrozen.width) : insideRawX
+                // 内側 py も帯下限 H_F でクランプ (v0.6 — 横の insideViewportX と対称。小数 vy の隅
+                // すきまでスクロール帯 endRow が凍結帯へ潜る dy ギャップを閉塞)
+                const insideRawY = cornerViewportY - 1
+                const insideViewportY = source.endRow >= pressFrozen.rows && pressFrozen.height > 0 ? Math.max(insideRawY, pressFrozen.height) : insideRawY
+                grabOffsetRef.current = { dx: event.clientX - (rect.left + insideViewportX * zPress), dy: event.clientY - (rect.top + insideViewportY * zPress) }
+            } else {
+                grabOffsetRef.current = { dx: 0, dy: 0 }
+            }
+            capturedPointerRef.current = event.pointerId
+            try {
+                // jsdom は InvalidPointerId を投げうる — 失敗時は mouse フォールバック (両機械と同型)
+                node.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)
+            // スクローラーは押下では起動しない (最初の実 pointermove で起動 — scrollerActiveRef
+            // の docstring 参照。押下直後のプレビューはソース矩形 = 拡張ゼロ)
+            p.writeFillPreview(sourceRangeRef.current)
+        }
+
+        const onLostPointerCapture = (event: PointerEvent) => {
+            // capture 喪失は中断 (pointerId 照合つき — 選択未変更のため復元不要 §8.2)
+            if (!draggingRef.current || capturedPointerRef.current === null || event.pointerId !== capturedPointerRef.current) {
+                return
+            }
+            cleanupDrag()
+        }
+
+        node.addEventListener("pointerdown", onPointerDown)
+        node.addEventListener("lostpointercapture", onLostPointerCapture)
+        return () => {
+            node.removeEventListener("pointerdown", onPointerDown)
+            node.removeEventListener("lostpointercapture", onLostPointerCapture)
+            cleanupDrag()
+        }
+    }, [enabled, handleNodeRef, isOwnPointer, hitTest, buildFillFrame, cleanupDrag, confirmFill])
+
+    return useMemo(
+        () => ({
+            isDragging: () => draggingRef.current,
+            // fill のプレビューは専用ノード — 選択矩形の減算スタイルとは無関係 (常に加算)
+            getDragMode: (): "add" | "subtract" => "add",
+            // ドラッグ中は選択もデータも書いていない — 中断 = 消灯 + ref リセットのみ
+            abortDrag: () => {
+                if (draggingRef.current) {
+                    cleanupDrag()
+                }
+            },
+            cancelDrag: cleanupDrag,
+        }),
+        [cleanupDrag],
+    )
+}

package/src/popover/CommentPopover.tsx

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Default comment thread popover (v0.8 §4.1.16): the existing thread (author,
+ * timestamp, text — every entry keeps its consumer id) followed by a reply textarea and a Post
+ * button. Posting commits the WHOLE thread `[...current (with ids), { text }]` — the package never
+ * mints an id, author or clock (design v5 "Comments"); a blank reply posts nothing. Keys:
+ * Ctrl+Enter posts (retries after a rejection), Escape closes. Leaving by focus closes without
+ * posting. DOM hooks: `data-aqsp-popover="comment"`, `data-aqsp-popover-title`,
+ * `data-aqsp-comment-thread`, `data-aqsp-comment-id`, `data-aqsp-comment-input`,
+ * `data-aqsp-popover-post`, `data-aqsp-popover-close`, `data-aqsp-popover-rejected`.
+ *
+ * 既定のコメントスレッド (v0.8 §4.1.16): 既存スレッド (著者 / 時刻 / 本文 — 各件は consumer の id を
+ * 保つ) + 返信 textarea + 投稿ボタン。投稿はスレッド全体 `[...current (id つき), { text }]` を
+ * commit する — id / 著者 / 時計はパッケージが採番しない (設計 v5「Comments」)。空の返信は投稿
+ * しない。キー: Ctrl+Enter 投稿 (拒否後は再試行)、Escape で閉じる。フォーカス離脱は投稿せず閉じる。
+ */
+
+import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import type { CommentPopoverContext } from "./usePopovers.ts"
+
+export type CommentPopoverProps = { ctx: CommentPopoverContext; labels: SpreadsheetLabels }
+
+/**
+ * Renders the comment thread and the reply form for one cell.
+ * 1 セルのコメントスレッドと返信フォームを描画する。
+ */
+export const CommentPopover = ({ ctx, labels }: CommentPopoverProps): ReactNode => {
+    const [reply, setReply] = useState("")
+    const titleId = useId()
+    const settlingRef = useRef(false)
+
+    const settle = (action: () => void): void => {
+        settlingRef.current = true
+        try {
+            action()
+        } finally {
+            settlingRef.current = false
+        }
+    }
+    const post = (): void => {
+        // 空 (空白のみ) の返信は投稿しない
+        if (reply.trim() === "") {
+            return
+        }
+        // 既存は id つきのまま verbatim、新規は id なし — 採番は consumer
+        settle(() => ctx.commit([...ctx.current, { text: reply }]))
+    }
+    const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>): void => {
+        if (event.key === "Escape") {
+            event.preventDefault()
+            settle(ctx.close)
+            return
+        }
+        if (event.key === "Enter" && (event.ctrlKey || event.metaKey) && !event.altKey && !event.shiftKey) {
+            event.preventDefault()
+            post()
+        }
+    }
+    const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
+        if (settlingRef.current || (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))) {
+            return
+        }
+        // 拒否状態は開いたまま (明示操作待ち)、それ以外の離脱は閉じる
+        if (ctx.rejected) {
+            return
+        }
+        settle(ctx.close)
+    }
+
+    return (
+        <div className="aqsp-popover-comment" data-aqsp-popover="comment" data-aqsp-popover-rejected={ctx.rejected ? "" : undefined} role="dialog" aria-labelledby={titleId} onBlur={onBlur}>
+            <div className="aqsp-popover-title" data-aqsp-popover-title="" id={titleId}>
+                {resolveLabel(labels, "commentTitle")}
+                <span className="aqsp-popover-count" data-aqsp-comment-count="">
+                    {resolveLabel(labels, "commentCount", ctx.current.length)}
+                </span>
+            </div>
+            <ul className="aqsp-popover-thread" data-aqsp-comment-thread="">
+                {ctx.current.map((comment) => (
+                    <li key={comment.id} className="aqsp-popover-comment-item" data-aqsp-comment-id={comment.id}>
+                        <span className="aqsp-popover-comment-author">{comment.author}</span>
+                        <time className="aqsp-popover-comment-time" dateTime={comment.createdAt}>
+                            {comment.createdAt}
+                        </time>
+                        <p className="aqsp-popover-comment-text">{comment.text}</p>
+                    </li>
+                ))}
+            </ul>
+            <textarea
+                className="aqsp-popover-textarea"
+                data-aqsp-comment-input=""
+                data-aqsp-popover-autofocus=""
+                value={reply}
+                aria-label={resolveLabel(labels, "commentReply")}
+                aria-invalid={ctx.rejected ? true : undefined}
+                onChange={(event) => setReply(event.currentTarget.value)}
+                onKeyDown={onKeyDown}
+            />
+            <div className="aqsp-popover-actions">
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-post="" onClick={post}>
+                    {resolveLabel(labels, "commentPost")}
+                </button>
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={() => settle(ctx.close)}>
+                    ×
+                </button>
+            </div>
+        </div>
+    )
+}

package/src/popover/LinkPopover.tsx

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Default hyperlink editor popover (v0.8 §4.1.16): text + URL fields, Save, an Open
+ * button only when the host declared `onHyperlinkOpen` (`ctx.canOpen`) and the cell has a link,
+ * and Close. The URL is validated through `normalizeHyperlink` on every keystroke: an
+ * unnormalisable non-empty value marks the popover invalid (`data-aqsp-link-invalid`,
+ * `aria-invalid`) and Save is refused — the commit only ever carries a normalised href or null
+ * (empty field = clear the link). Saving an empty text draft with a valid URL commits the href
+ * as the display text (Sheets / Excel parity — a link on an empty cell must stay visible).
+ * Keys: Enter saves, Escape closes. Leaving by focus closes
+ * without saving. DOM hooks: `data-aqsp-popover="link"`, `data-aqsp-popover-title`,
+ * `data-aqsp-link-text`, `data-aqsp-link-url`, `data-aqsp-popover-save`, `data-aqsp-link-open`
+ * (the Open button — distinct from the layer's anchor open-state `data-aqsp-popover-open`),
+ * `data-aqsp-popover-close`, `data-aqsp-popover-rejected`.
+ *
+ * 既定のハイパーリンクエディタ (v0.8 §4.1.16): text + URL 欄、保存、Open (ホストが onHyperlinkOpen を
+ * 宣言し (`ctx.canOpen`) セルにリンクがあるときだけ)、閉じる。URL は打鍵毎に normalizeHyperlink で
+ * 検証し、正規化不能な非空値は不正表示 (`data-aqsp-link-invalid` / `aria-invalid`) で保存を拒む —
+ * commit は常に正規化済み href か null (空欄 = リンク消去) だけを運ぶ。空の text 下書き + 有効 URL の
+ * 保存は href を表示テキストとして commit する (Sheets / Excel 同等 — 空セルのリンクを見えないままに
+ * しない)。キー: Enter 保存、Escape で閉じる。フォーカス離脱は保存せず閉じる。
+ */
+
+import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
+import { normalizeHyperlink } from "../model/cellAnnotations.ts"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import type { LinkPopoverContext } from "./usePopovers.ts"
+
+export type LinkPopoverProps = { ctx: LinkPopoverContext; labels: SpreadsheetLabels }
+
+/**
+ * Renders the hyperlink editor for one cell.
+ * 1 セルのハイパーリンクエディタを描画する。
+ */
+export const LinkPopover = ({ ctx, labels }: LinkPopoverProps): ReactNode => {
+    const [text, setText] = useState(ctx.current.text)
+    const [url, setUrl] = useState(ctx.current.url === undefined ? "" : ctx.current.url)
+    const titleId = useId()
+    const settlingRef = useRef(false)
+    // 空欄はリンク消去、それ以外は正規化 (null = 不正)
+    const normalized = url.trim() === "" ? null : normalizeHyperlink(url)
+    const invalid = url.trim() !== "" && normalized === null
+
+    const settle = (action: () => void): void => {
+        settlingRef.current = true
+        try {
+            action()
+        } finally {
+            settlingRef.current = false
+        }
+    }
+    const save = (): void => {
+        // 不正 URL は保存しない (表示で知らせる — 代替値は作らない)
+        if (invalid) {
+            return
+        }
+        // 空テキスト + 有効 URL は href を表示テキストへ写す (Sheets / Excel 同等 — 見えないリンクを作らない)
+        settle(() => ctx.commit({ text: text === "" && normalized !== null ? normalized : text, url: normalized }))
+    }
+    const onKeyDown = (event: KeyboardEvent<HTMLInputElement>): void => {
+        if (event.key === "Escape") {
+            event.preventDefault()
+            settle(ctx.close)
+            return
+        }
+        if (event.key === "Enter" && !event.altKey && !event.shiftKey) {
+            event.preventDefault()
+            save()
+        }
+    }
+    const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
+        if (settlingRef.current || (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))) {
+            return
+        }
+        if (ctx.rejected) {
+            return
+        }
+        settle(ctx.close)
+    }
+
+    return (
+        <div className="aqsp-popover-link" data-aqsp-popover="link" data-aqsp-popover-rejected={ctx.rejected ? "" : undefined} data-aqsp-link-invalid={invalid ? "" : undefined} role="dialog" aria-labelledby={titleId} onBlur={onBlur}>
+            <div className="aqsp-popover-title" data-aqsp-popover-title="" id={titleId}>
+                {resolveLabel(labels, "linkTitle")}
+            </div>
+            <label className="aqsp-popover-field">
+                <span className="aqsp-popover-field-label">{resolveLabel(labels, "linkTextField")}</span>
+                <input className="aqsp-popover-input" data-aqsp-link-text="" type="text" value={text} onChange={(event) => setText(event.currentTarget.value)} onKeyDown={onKeyDown} />
+            </label>
+            <label className="aqsp-popover-field">
+                <span className="aqsp-popover-field-label">{resolveLabel(labels, "linkUrlField")}</span>
+                <input className="aqsp-popover-input" data-aqsp-link-url="" data-aqsp-popover-autofocus="" type="url" value={url} aria-invalid={invalid || ctx.rejected ? true : undefined} onChange={(event) => setUrl(event.currentTarget.value)} onKeyDown={onKeyDown} />
+            </label>
+            <div className="aqsp-popover-actions">
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" disabled={invalid} onClick={save}>
+                    {resolveLabel(labels, "linkSave")}
+                </button>
+                {ctx.canOpen && ctx.current.url !== undefined ? (
+                    <button type="button" className="aqsp-popover-button" data-aqsp-link-open="" onClick={ctx.open}>
+                        {resolveLabel(labels, "linkOpen")}
+                    </button>
+                ) : null}
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={() => settle(ctx.close)}>
+                    ×
+                </button>
+            </div>
+        </div>
+    )
+}