@aiquants/spreadsheet 0.8.0

package/src/editor/useCellEditor.ts

@@ -0,0 +1,708 @@
+/**
+ * @fileoverview Cell editing session state machine (§6.7.1): idle / editing(edit) /
+ * editing(replace). Owns the session state, the composition tracking, the grid-exit focusout
+ * commit and the suppressFocusoutCommit double-commit guard. All terminal transitions funnel
+ * through the idempotent finishEdit({ rearm }). The EDITING keymap columns are dispatched by
+ * useGridKeyboard through the seams returned here (single keydown owner = the §6.6.1 table
+ * stays one auditable dispatch — the plan's "編集中は編集セッションへ委譲" is realized as
+ * decision seams, not a second keydown listener). v0.8 (plan §4.2.6) adds four capability
+ * branches, each inert when the root does not declare it: the formula seed (resolveEditText —
+ * getCellFormula), the edit paint (resolveEditPaint / editPaintRef — inline text-level styles
+ * on the sink, retired at close), the validation gate (validateCommit — a rejected verdict
+ * follows the applyEdits-rejection path without reaching the adapter) and formula POINTING
+ * (§2.7): the predicate is evaluated LAZILY on the live sink at every decision point
+ * (`isPointingPrefix(sink.value, sink.selectionStart)`), the state is the arm flag —
+ * off at every session start (an F2 / dblclick session on an existing formula is Excel Edit
+ * mode: the first Arrow moves the caret), armed by an input that leaves the caret right after
+ * a trigger (`=`, `(`, an operator… — Sheets' operator rule / Excel Enter mode), toggled by
+ * F2 — plus the extension anchor of the pointed token (the corner a Shift+Arrow chain is
+ * pinned to — Excel / Sheets keyboard pointing), and `data-aqsp-pointing` is a progressive
+ * visual hint written after input / selectionchange and after every mutator here — never a
+ * decision input.
+ *
+ * セル編集セッション状態機械 (§6.7.1)。idle / editing(edit) / editing(replace) のセッション
+ * 状態・composition 追跡・グリッド外 focusout commit・suppressFocusoutCommit を所有する。
+ * 終端遷移は冪等な finishEdit({ rearm }) 1 本。編集列のキーディスパッチは useGridKeyboard が
+ * ここの返すシーム経由で行う (§6.6.1 の表を 1 枚の監査可能 dispatch に保つ)。v0.8 (計画
+ * §4.2.6) は root が宣言しない限り不活性な 4 つの能力分岐を追加: 数式シード (resolveEditText —
+ * getCellFormula)、エディタ塗り (resolveEditPaint / editPaintRef — シンクへのインライン文字
+ * 装飾、終了で退役)、検証ゲート (validateCommit — 拒否判定はアダプタへ届かず applyEdits 拒否と
+ * 同じ経路)、数式ポインティング (§2.7): 述語は判断点ごとに live シンク上でその場評価
+ * (`isPointingPrefix(sink.value, sink.selectionStart)`)、状態は武装フラグ — セッション
+ * 開始で非武装 (F2 / dblclick で開いた既存数式は Excel の Edit モード: 最初の矢印はキャレット
+ * 移動)、キャレットを契機 (`=` `(` 演算子…) の直後に置く入力で武装 (Sheets の演算子契機 /
+ * Excel の Enter モード)、F2 でトグル — と指しトークンの伸長アンカー (Shift+Arrow 連鎖が固定
+ * する角 — Excel / Sheets のキーボードポインティング)、`data-aqsp-pointing` は input /
+ * selectionchange 後と当フックの各変更操作後に書く漸進的な視覚ヒントであり判断根拠にはしない。
+ */
+
+import { type RefObject, useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type { CellCoord, CellRange } from "../model/cellCoord.ts"
+import type { CellAlign } from "../model/cellFormat.ts"
+import { type EditPaint, IDLE_EDIT_PAINT } from "../model/cellPaint.ts"
+import { type CellEdit, type EditRejection, resolveEditText, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import type { ValidationVerdict } from "../model/dataValidation.ts"
+import { cycleAnchorAt, findReferenceAt, formatRangeReference, isPointingPrefix, type PointingTarget, type ReferenceAxis } from "../model/formulaRefs.ts"
+
+/** Editing mode (§6.7.1 state diagram). / 編集モード。 */
+export type EditingMode = "edit" | "replace"
+
+/** Sink snapshot for the reference-drag Escape restore (value + caret range before the drag). / 参照ドラッグの Escape 復元用シンク断面 (ドラッグ前の value とキャレット区間)。 */
+export type SinkSnapshot = { value: string; selectionStart: number; selectionEnd: number }
+
+/**
+ * The reference cursor over the token under the caret: `origin` is the extension anchor —
+ * the cell of the last coordinate (non-Shift) insertion when it lies on a corner of the
+ * token, else the token's start (Excel's typed-token rule) —, `cursor` the corner diagonal
+ * to it (the end arrow keys move — `makeRange(origin, step(cursor))` is exactly Excel /
+ * Sheets Shift+Arrow pointing), `axis` the token's kind (cell / rectangle, column band, row
+ * band). An insertion point (no token) yields the editing cell for both ends.
+ * キャレット下トークン上の参照カーソル: `origin` は伸長アンカー — 最後の座標 (非 Shift) 挿入
+ * のセルがトークンの角に乗るならその角、乗らなければトークン始端 (Excel の手打ちトークン規則)
+ * —、`cursor` はその対角 (矢印で動く終端 — `makeRange(origin, step(cursor))` が Excel /
+ * Sheets の Shift+Arrow ポインティングそのもの)、`axis` はトークン種 (セル / 矩形・列帯・
+ * 行帯)。挿入点 (トークンなし) は両端とも編集中セル。
+ */
+export type ReferenceCursor = { origin: CellCoord; cursor: CellCoord; axis: ReferenceAxis }
+
+/**
+ * The pointing seams consumed by the pointer machines and the keymap (a structural subset of
+ * {@link CellEditor}; the root wires them to machines built before the editor through refs).
+ * ポインタ機械とキーマップが消費するポインティングシーム ({@link CellEditor} の構造的部分集合。
+ * エディタより先に構築される機械へは root が ref 経由で結線する)。
+ */
+export type PointingSeams = {
+    /** Live predicate (§2.7): getCellFormula declared ∧ session open ∧ armed ∧ `isPointingPrefix(sink.value, sink.selectionStart) !== null` — evaluated on the sink at call time, never cached. / live 述語 (§2.7): getCellFormula 宣言 ∧ セッション中 ∧ 武装 ∧ 述語成立 — 呼ばれた時点のシンクで評価、キャッシュしない。 */
+    getPointing: () => boolean
+    /** The reference cursor under the caret (origin = the extension anchor it re-pins onto the token), or null when not pointing. / キャレット下の参照カーソル (origin = トークン上へ再ピンする伸長アンカー。非ポインティング時は null)。 */
+    getReferenceCursor: () => ReferenceCursor | null
+    /** Inserts (`{ insertAt }`) or replaces (`{ replace }`) the pointed reference text at the predicate's target and parks the caret right after it; a coordinate target also becomes the extension anchor (a range target preserves it); a no-op when not pointing. / 述語の行き先へ参照文字列を挿入 / 置換しキャレットをその直後へ (座標の指しは伸長アンカーにもなり、レンジ置換はそれを保つ。非ポインティング時は no-op)。 */
+    insertReference: (target: CellCoord | CellRange, axis: ReferenceAxis) => void
+    /** F2 arm toggle (Excel's Edit ⇄ Enter — a session opens disarmed, a typed trigger arms it) — false (nothing toggled, key falls through) without the capability or a session. / F2 武装トグル (Excel の Edit ⇄ Enter — セッションは非武装で開き、契機の入力で武装) — 能力 / セッションが無ければ false (キーは素通し)。 */
+    togglePointingArm: () => boolean
+    /** F4: cycles the reference under the caret; false when nothing was cycled (key falls through). / F4: キャレット下参照の $ 循環。循環対象なしは false (素通し)。 */
+    cycleAnchorAtCaret: () => boolean
+}
+
+type UseCellEditorParams = {
+    /** Rewire gate (§6.9-1 empty branch — same as the other wiring hooks). / 再結線ゲート。 */
+    enabled: boolean
+    sinkRef: RefObject<HTMLTextAreaElement | null>
+    rootRef: RefObject<HTMLElement | null>
+    adapter: SpreadsheetDataAdapter
+    /** The §6.9-2 write funnel: the transaction id on success (the edit version is bumped and the clip commit-discarded), null when the adapter rejected (or the transaction was empty); the caller declares the rejection context it relays to onEditRejected. / §6.9-2 の書込漏斗: 成功はトランザクション id (bumpEdit + クリップの commit 破棄)、アダプタ拒否 (または空トランザクション) は null。呼び手が onEditRejected へ中継される拒否文脈を宣言する。 */
+    commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    getActive: () => CellCoord
+    ensureCellVisible: (cell: CellCoord) => void
+    focusSink: () => void
+    rearmSink: () => void
+    /** Discards the armed clip (copy / cut ants) on edit start (§6.5.4-4 — Excel: typing dismisses the ants). / 編集開始で装填クリップ (copy / cut アンツ) を破棄する。 */
+    discardClip: () => void
+    /** Drag/edit mutual exclusion probe (§6.7.1 entry guard). / ドラッグと編集セッションの併存禁止 (冒頭ガード)。 */
+    isDragging: () => boolean
+    /**
+     * The cell's effective alignment for the editing textarea (Excel keeps the cell alignment
+     * while editing in place). null = the adapter has no getCellFormat capability — the sink's
+     * text-align is left untouched (v0.1 identity, distinct from an explicit "left").
+     * 編集中 textarea へ適用するセルの実効揃え (Excel はその場編集でもセル揃えを保つ)。null =
+     * getCellFormat 能力なし — text-align に触れない (v0.1 恒等・明示 "left" とは別物)。
+     */
+    resolveEditAlign: (cell: CellCoord) => CellAlign | null
+    /**
+     * v0.8 capability: the text-level paint for the sink (plan §4.2.6 / §2.3). Undefined =
+     * the root does not declare it — no inline style is written (v0.7 identity); null from the
+     * resolver = getCellFormat undeclared (same identity). The paint's style keys are applied
+     * to the sink at session start and cleared at close.
+     * v0.8 能力: シンクの文字装飾塗り (計画 §4.2.6 / §2.3)。undefined = root 未宣言 — インライン
+     * スタイルを書かない (v0.7 恒等)。resolver の null = getCellFormat 未宣言 (同じ恒等)。塗りの
+     * style キーはセッション開始でシンクへ書き、終了で消す。
+     */
+    resolveEditPaint?: (cell: CellCoord) => EditPaint | null
+    /** Root-owned paint channel read by the overlay (lineBoxPx / verticalAlign for the sink's padding); written on start / refresh, reset to IDLE_EDIT_PAINT at close. / root 所有の塗りチャネル (overlay が lineBoxPx / verticalAlign を読む)。開始 / 再計算で書き、終了で IDLE_EDIT_PAINT へ戻す。 */
+    editPaintRef?: RefObject<EditPaint>
+    /** Overlay repaint after an editing-column format toggle recomputed the paint. / 編集列の書式トグルで塗りを再計算した後の overlay 再描画。 */
+    repaintOverlay?: () => void
+    /**
+     * v0.8 capability: the commit-time validation gate (getCellValidation strict rules — the
+     * root resolves the rule, gates on `strict` and notifies onValidationRejected). A rejected
+     * verdict never reaches commitEdits and follows the same keep / discard path as an
+     * applyEdits rejection. Undefined = no validation (v0.7 identity).
+     * v0.8 能力: 確定時の検証ゲート (getCellValidation の strict 規則 — 規則解決・strict 判定・
+     * onValidationRejected 通知は root)。拒否判定は commitEdits へ進まず applyEdits 拒否と同じ
+     * keep / discard 経路。undefined = 検証なし (v0.7 恒等)。
+     */
+    validateCommit?: (cell: CellCoord, text: string) => ValidationVerdict
+}
+
+/** Seams consumed by the keymap and the pointer machines. / キーマップ / ポインタ機械が消費するシーム。 */
+export type CellEditor = PointingSeams & {
+    isEditing: () => boolean
+    /** Editing mode probe — null = idle; drives the editing Arrow split (replace = commit + move, edit = native). / null = idle。編集列の Arrow 分岐用。 */
+    getEditingMode: () => EditingMode | null
+    /** True only inside requestCommit's composition-confirming blur — an internal focusout (focus returns to the sink right after), not a grid exit. / requestCommit の composition 確定 blur の間だけ true (内部 focusout — 直後にシンクへ戻る。グリッド脱出ではない)。 */
+    isFocusoutSuppressed: () => boolean
+    /**
+     * Commits the in-flight session (composition force-confirmed via blur when needed) and
+     * re-arms. Returns false when applyEdits rejected — the session stays alive and the
+     * caller aborts its own action (§6.4.3-2 order contract).
+     * 飛行中セッションを確定して再武装 (composition 中は blur で強制確定)。applyEdits 拒否時は
+     * false を返しセッション維持 — 呼び出し側が自分の動作を中断する (§6.4.3-2)。
+     */
+    requestCommit: () => boolean
+    /** Cancels the session discarding the value (editing-Escape row). / 値破棄キャンセル。 */
+    cancelEdit: () => void
+    /** Opens a session on the active cell (edit = existing value + caret end, replace = ""); caretIndex places the ED-1 click-point caret (geometrically clamped to the text length; a formula seed always parks the caret at the end). / active セルでセッションを開く (edit = 既存値 + キャレット末尾、replace = "")。caretIndex は ED-1 のクリック位置キャレット (テキスト長へ幾何 clamp。数式シードは常に末尾)。 */
+    startEdit: (mode: EditingMode, caretIndex?: number) => void
+    /** Sink snapshot for the reference drag (null without a sink). / 参照ドラッグ用のシンク断面 (シンク不在は null)。 */
+    captureSink: () => SinkSnapshot | null
+    /** Restores a snapshot (reference-drag Escape: the token reverts, the session stays). / 断面の復元 (参照ドラッグの Escape: トークンは戻りセッションは残る)。 */
+    restoreSink: (snapshot: SinkSnapshot) => void
+    /** Replaces the sink's selection range with `text` and parks the caret after it (editing-column insertDate / insertTime). / シンクの選択区間を `text` で置換しキャレットを直後へ (編集列の insertDate / insertTime)。 */
+    insertAtCaret: (text: string) => void
+    /** The session's live text, or null when idle (editing-column fillSelection). / セッションの現在文字列 (idle は null — 編集列の fillSelection)。 */
+    getSessionText: () => string | null
+    /** Recomputes and re-applies the edit paint after an editing-column format toggle, then repaints the overlay. / 編集列の書式トグル後に塗りを再計算・再適用し overlay を再描画。 */
+    refreshPaint: () => void
+    /** React state mirror for the overlay's editing prop (§6.7.2-4). / overlay の editing prop 用ミラー。 */
+    editing: boolean
+}
+
+/** Progressive pointing hint attribute on the sink (visual only — never a decision input). / シンクのポインティング視覚ヒント属性 (判断根拠にはしない)。 */
+const POINTING_ATTRIBUTE = "data-aqsp-pointing"
+
+/**
+ * Whether an input that left the caret at `caret` in `value` arms pointing: the prefix ends
+ * in a trigger (`{ insertAt }` — `=`, `=SUM(`, `=A1+`), i.e. the user just typed the trigger
+ * or deleted back to it (Sheets: range selection starts right after an operator; Excel: Enter
+ * mode). A caret on / right after a reference (`{ replace }` — `=A1+B1|`, `=A1+B1|2`) is
+ * mid-spelling and never arms, so the reference under the caret is not rewritten by an Arrow.
+ * 入力でキャレットが `value` の `caret` に置かれたときポインティングを武装するか: 接頭辞が契機で
+ * 終わる (`{ insertAt }` — `=` / `=SUM(` / `=A1+`) = 契機を打った / 契機まで削った直後 (Sheets の
+ * 「演算子の直後で範囲選択が始まる」規則、Excel の Enter モード)。参照の上 / 直後のキャレット
+ * (`{ replace }` — `=A1+B1|` / `=A1+B1|2`) は綴りの途中なので武装せず、矢印がキャレット下の参照を
+ * 書き換えることはない。
+ */
+const isTriggerInput = (value: string, caret: number): boolean => {
+    const target = isPointingPrefix(value, caret)
+    return target !== null && "insertAt" in target
+}
+
+/** Clears the given camelCase style keys on the sink (an empty assignment removes the declaration). / 指定の camelCase style キーをシンクから消す (空文字代入で宣言が消える)。 */
+const clearStyleKeys = (sink: HTMLTextAreaElement, keys: readonly string[]): void => {
+    // Object.assign は CSSOM の camelCase プロパティ代入 — "" は宣言の削除
+    Object.assign(sink.style, Object.fromEntries(keys.map((key) => [key, ""])))
+}
+
+/**
+ * Builds the editing session machine wired to the sink.
+ * シンクへ結線した編集セッション機械を構築する。
+ */
+export const useCellEditor = (params: UseCellEditorParams): CellEditor => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    /** In-flight session (null = idle); commit writes to the cell captured at start. / 飛行中セッション。commit は開始時に捕捉したセルへ書く。 */
+    const sessionRef = useRef<{ cell: CellCoord; mode: EditingMode } | null>(null)
+    const [editing, setEditing] = useState(false)
+    const isComposingRef = useRef(false)
+    const suppressFocusoutCommitRef = useRef(false)
+    /** The arming half of the pointing state (§2.7): false at every session start (the seed never arms: an F2 / dblclick session on an existing formula is Excel Edit mode), set by a trigger input (`isTriggerInput`), toggled by F2. / ポインティング状態の武装側 (§2.7): セッション開始で false (シードは武装しない: F2 / dblclick の既存数式は Excel の Edit モード)、契機の入力 (`isTriggerInput`) で true、F2 でトグル。 */
+    const pointingArmedRef = useRef(false)
+    /** The anchor half of the pointing state (§2.7): the extension anchor of the pointed token — set by every coordinate (non-Shift) insertion (plain Arrow / cell press / header press / drag press), preserved across range replacements (Shift+Arrow / drag move), re-pinned onto the token by getReferenceCursor (typed tokens anchor at their start), collapsed by typing input / insertAtCaret / restoreSink and at session boundaries. / ポインティング状態のアンカー側 (§2.7): 指しトークンの伸長アンカー — 座標 (非 Shift) 挿入 (素の Arrow / セル押下 / ヘッダー押下 / ドラッグ押下) のたびに設定、レンジ置換 (Shift+Arrow / ドラッグ move) では保持、getReferenceCursor がトークン上へ再ピン (手打ちトークンは始端)、印字入力 / insertAtCaret / restoreSink とセッション境界で畳む。 */
+    const pointingAnchorRef = useRef<CellCoord | null>(null)
+    /** The paint currently written on the sink (its style keys are what close / refresh clear). / 現在シンクへ書かれている塗り (close / refresh が消すのはこのキー集合)。 */
+    const sessionPaintRef = useRef<EditPaint>(IDLE_EDIT_PAINT)
+
+    /**
+     * The pointing decision (§2.7), evaluated on the live sink at the moment of the call:
+     * capability ∧ session ∧ armed ∧ predicate. Returns the sink together with the predicate's
+     * target so the mutators apply it without a second evaluation; null = not pointing.
+     * ポインティング判断 (§2.7) — 呼ばれた瞬間の live シンクで評価: 能力 ∧ セッション ∧ 武装 ∧
+     * 述語。変更操作が二重評価せず適用できるようシンクと行き先を組で返す。null = 非ポインティング。
+     */
+    const pointingTarget = useCallback((): { sink: HTMLTextAreaElement; target: PointingTarget } | null => {
+        const p = paramsRef.current
+        const sink = p.sinkRef.current
+        // 能力分岐 (getCellFormula 未宣言 = 数式という概念が無い — v0.7 恒等) + セッション + 武装 + シンク
+        if (p.adapter.getCellFormula === undefined || sessionRef.current === null || !pointingArmedRef.current || sink === null) {
+            return null
+        }
+        // 純述語をその場評価 (キャッシュしたフラグを判断根拠にしない — §0 規律)
+        const target = isPointingPrefix(sink.value, sink.selectionStart)
+        return target === null ? null : { sink, target }
+    }, [])
+
+    /** Writes the progressive `data-aqsp-pointing` hint with same-value suppression. / 漸進的な `data-aqsp-pointing` ヒントを同値抑止で書く。 */
+    const syncPointingHint = useCallback((): void => {
+        const sink = paramsRef.current.sinkRef.current
+        if (sink === null) {
+            return
+        }
+        const pointing = pointingTarget() !== null
+        // 同値抑止 (属性の毎回書換は MutationObserver 系の消費者を無駄に起こす)
+        if (pointing !== sink.hasAttribute(POINTING_ATTRIBUTE)) {
+            if (pointing) {
+                sink.setAttribute(POINTING_ATTRIBUTE, "")
+            } else {
+                sink.removeAttribute(POINTING_ATTRIBUTE)
+            }
+        }
+    }, [pointingTarget])
+
+    /**
+     * Applies the edit paint for `cell` to the sink (capability branch: the resolver absent or
+     * returning null writes nothing and records IDLE) and mirrors it into the root's channel.
+     * `cell` の塗りをシンクへ適用 (能力分岐: resolver 不在 / null は何も書かず IDLE を記録) し
+     * root のチャネルへ写す。
+     */
+    const applyPaint = useCallback((sink: HTMLTextAreaElement, cell: CellCoord): void => {
+        const p = paramsRef.current
+        // 能力分岐: root が塗りを宣言しない限りインライン style には一切触れない (v0.7 恒等)
+        if (p.resolveEditPaint === undefined) {
+            return
+        }
+        const resolved = p.resolveEditPaint(cell)
+        // null = getCellFormat 未宣言 (同じ恒等)。IDLE は identity 比較で「書くものなし」
+        const paint = resolved === null ? IDLE_EDIT_PAINT : resolved
+        if (paint !== IDLE_EDIT_PAINT) {
+            Object.assign(sink.style, paint.style)
+        }
+        sessionPaintRef.current = paint
+        if (p.editPaintRef !== undefined) {
+            p.editPaintRef.current = paint
+        }
+    }, [])
+
+    /** Retires the paint written by applyPaint (style keys cleared, channels reset to IDLE). / applyPaint が書いた塗りの退役 (style キー消去、チャネルは IDLE へ)。 */
+    const retirePaint = useCallback((sink: HTMLTextAreaElement): void => {
+        clearStyleKeys(sink, Object.keys(sessionPaintRef.current.style))
+        sessionPaintRef.current = IDLE_EDIT_PAINT
+        const editPaintRef = paramsRef.current.editPaintRef
+        if (editPaintRef !== undefined) {
+            editPaintRef.current = IDLE_EDIT_PAINT
+        }
+    }, [])
+
+    /**
+     * The single terminal transition (idempotent — no-op when idle). commit=true attempts
+     * the validation gate then applyEdits; on rejection `onReject` decides the session's fate
+     * and is DECLARED up front so the wrapper can relay it to onEditRejected: "keep" (in-grid
+     * commits — the session stays open with the typed value) or "discard" (grid-exit focusout
+     * — the session closes, the text-align / paint retire and the sink is re-armed immediately
+     * without touching focus); both return false. An UNCHANGED commit (sink text equals the
+     * cell's canonical text — the formula source for a formula cell) never reaches the gate or
+     * applyEdits: the session just ends (Sheets-like — opening an editor and leaving without a
+     * change is not a write, so read-only hosts get a smooth focus-out instead of a rejection
+     * loop).
+     * 終端遷移の一本化 (冪等 — idle なら no-op)。commit=true は検証ゲート → applyEdits の順に
+     * 試み、拒否時のセッションの行方は `onReject` が**事前に宣言**する (ラッパーが onEditRejected
+     * へ中継できるように): "keep" (グリッド内確定 — 入力値ごと維持) / "discard" (グリッド外
+     * focusout — セッションを閉じ、text-align / 塗りを退役し、フォーカスに触れずシンクを即再武装)。
+     * いずれも false。**無変更 commit** (sink 値 = セルの正準テキスト — 数式セルは数式ソース) は
+     * ゲートにも applyEdits にも進めずセッション終了のみ (Sheets 同型 — 開いて閉じただけは書込
+     * でない。読み取り専用ホストのフォーカスアウトが拒否ループに化けない)。
+     */
+    const finishEdit = useCallback(
+        (options: { rearm: boolean } & ({ commit: false } | { commit: true; onReject: "keep" | "discard" })): boolean => {
+            const p = paramsRef.current
+            const session = sessionRef.current
+            if (session === null) {
+                return true
+            }
+            /** Closes the session unconditionally (shared by the success path and the discard path). / セッションを無条件に閉じる (成功経路と破棄経路の共有部)。 */
+            const closeSession = (): void => {
+                sessionRef.current = null
+                pointingAnchorRef.current = null
+                const sink = p.sinkRef.current
+                if (sink !== null) {
+                    // 編集専用の text-align / 塗り / ポインティングヒントを退役 (次セッションの startEdit が改めて解決する)
+                    sink.style.removeProperty("text-align")
+                    retirePaint(sink)
+                    sink.removeAttribute(POINTING_ATTRIBUTE)
+                }
+                setEditing(false)
+            }
+            if (options.commit) {
+                const sink = p.sinkRef.current
+                const text = sink === null ? "" : sink.value
+                // 無変更判定は正準テキストとの厳密比較 (SSOT — resolveEditText が唯一の比較先: 数式セルは
+                // 数式ソース、それ以外は getCellText)。比較前に正準側の改行だけ LF へ正規化する (textarea の
+                // API value は HTML 仕様で CR / CRLF → LF 正規化済み — CR を含むホストデータでは素の比較が
+                // 構造的に不成立になり、無操作 commit が正規化書込 + 読み取り専用ホストの拒否 UX に化ける。
+                // R4 是正)。replace モードで「打って全消し → 確定」は原文と異なるため従来どおり書込 (セルクリア)
+                const canonical = resolveEditText(p.adapter, session.cell.row, session.cell.col).text.replace(/\r\n?/g, "\n")
+                const unchanged = text === canonical
+                // 拒否文脈は呼び手が事前宣言する (onEditRejected はラッパーが発火 — ここで重ねて発火しない):
+                // keep = グリッド内確定 (セッション維持) / discard = グリッド外 focusout (破棄) の 2 値だけ
+                const rejection: EditRejection = { source: "edit", editSession: options.onReject === "keep" ? "kept" : "discarded" }
+                // 無変更は検証ゲートにも書込にも進まない (短絡)。検証ゲート (能力分岐) の拒否判定はアダプタへ
+                // 届けず applyEdits 拒否と同じ keep / discard 経路へ。commitEdits は成功でトランザクション id、
+                // 拒否で null (= 未確定)
+                const committed = unchanged || ((p.validateCommit === undefined || p.validateCommit(session.cell, text).ok) && p.commitEdits([{ row: session.cell.row, col: session.cell.col, text }], rejection) !== null)
+                if (!committed) {
+                    if (options.onReject === "discard") {
+                        // グリッド外 focusout の拒否 (§6.7.1): フォーカス無き宙吊りセッションを残さず、
+                        // 入力値を破棄して idle へ。シンクも即座に再武装して入力残留を掃除する
+                        // (rearmSink はフォーカスを動かさない — ユーザーが選んだ外部要素はそのまま)
+                        closeSession()
+                        p.rearmSink()
+                    }
+                    // keep: グリッド内経路では編集状態を維持 (bumpEdit されない) — Escape で取消 / 修正可
+                    return false
+                }
+            }
+            closeSession()
+            if (options.rearm) {
+                p.rearmSink()
+            }
+            return true
+        },
+        [retirePaint],
+    )
+
+    /**
+     * Opens a session on the active cell after the entry guards (§6.7.1 — F2 / printable /
+     * composition / dblclick all funnel here).
+     * 冒頭ガード通過後に active セルでセッションを開く (§6.7.1 — F2 / 印字 / composition /
+     * dblclick の全経路がここへ合流)。
+     */
+    const startEdit = useCallback(
+        (mode: EditingMode, caretIndex?: number) => {
+            const p = paramsRef.current
+            // ドラッグと編集セッションの併存状態を作らない (§6.7.1 冒頭ガード — F2 / 印字 / composition 全経路)
+            if (p.isDragging() || sessionRef.current !== null) {
+                return
+            }
+            // シンク不在 (アンマウント途中) の bail を副作用より先に — クリップ破棄や
+            // ensure-visible だけ走ってセッションが開かない片肺状態を作らない
+            const sink = p.sinkRef.current
+            if (sink === null) {
+                return
+            }
+            // 編集開始でクリップを破棄 (§6.5.4-4 — copy アンツも Excel 同様ここで消灯)
+            p.discardClip()
+            const active = p.getActive()
+            // active はスクロールで画面外に出得る — 画面外セルの上にエディタ / IME 候補窓を開かない (§6.7.1)
+            p.ensureCellVisible(active)
+            if (mode === "edit") {
+                // シードは resolveEditText (能力分岐: getCellFormula 宣言 + 数式なら数式ソース、それ以外は正準文字列)
+                const { text, isFormula } = resolveEditText(p.adapter, active.row, active.col)
+                sink.value = text
+                // ED-1: クリック位置キャレット。caretIndex はセル単位ゲートが有効なとき (renderCell
+                // 未宣言かつ**そのセルの**表示テキスト === 素の正準文字列) のみ届くため offset は正準長を
+                // 超えない (Math.min は契約の保険)。caretIndex 未指定はキャレット末尾 (F2 / 非対応環境 /
+                // 表示が素値と乖離するセル — v0.1 挙動)。数式セルは表示 (計算結果) と綴りが乖離するため
+                // クリック位置は写像できず常に末尾 (caret-from-point off)
+                const caret = caretIndex === undefined || isFormula ? text.length : Math.min(caretIndex, text.length)
+                sink.setSelectionRange(caret, caret)
+            } else {
+                // replace: value="" の設定 1 点で打鍵 / composition を流入させる (§6.6.2-5)
+                sink.value = ""
+            }
+            // Excel 同様、編集中もセルの実効揃えを textarea に維持 (能力なし = null は触らない恒等)
+            const editAlign = p.resolveEditAlign(active)
+            if (editAlign !== null) {
+                sink.style.textAlign = editAlign
+            }
+            // 文字装飾の塗り (能力分岐 — resolver 不在 / null は何も書かない)
+            applyPaint(sink, active)
+            // 唯一のポインティング状態は非武装で開く (§2.7): シードは武装契機でない — F2 / dblclick で
+            // 開いた既存数式 (`=A1+B1`) の最初の矢印は Excel の Edit モードどおりキャレット移動で、末尾の
+            // 参照を書き換えない。武装は契機の入力 (onInput の isTriggerInput) か F2 (togglePointingArm)。
+            // 非武装のため述語は構造的に不成立で、ヒント属性は前セッションの closeSession が除去済み
+            pointingArmedRef.current = false
+            pointingAnchorRef.current = null
+            sessionRef.current = { cell: active, mode }
+            setEditing(true)
+        },
+        [applyPaint],
+    )
+
+    const cancelEdit = useCallback(() => {
+        // 値破棄 (rearmSink が武装状態 value = " " 全選択へ戻す)。commit しない経路は onReject を持たない (型で排除)
+        finishEdit({ rearm: true, commit: false })
+    }, [finishEdit])
+
+    const requestCommit = useCallback((): boolean => {
+        const p = paramsRef.current
+        if (sessionRef.current === null) {
+            return true
+        }
+        const sink = p.sinkRef.current
+        if (isComposingRef.current && sink !== null) {
+            // composition 進行中の外クリック等 (§6.6.1 注記): blur が composition を確定させ value に
+            // 反映される。blur は relatedTarget=null の focusout を同期発火させるため、二重 commit を
+            // 抑止フラグで防ぐ (解除は try/finally — 降ろし忘れは次の正当な focusout commit を殺す)
+            suppressFocusoutCommitRef.current = true
+            try {
+                sink.blur()
+            } finally {
+                suppressFocusoutCommitRef.current = false
+            }
+            // グリッド内経路 (押下 / ヘッダー / バー帯) の確定 — 拒否はセッション維持 (keep)
+            if (!finishEdit({ rearm: false, commit: true, onReject: "keep" })) {
+                p.focusSink()
+                return false
+            }
+            // blur でフォーカスが外れている — 回収 + 再武装して押下処理へ返す (§6.6.1 注記の順序)
+            p.focusSink()
+            p.rearmSink()
+            return true
+        }
+        return finishEdit({ rearm: true, commit: true, onReject: "keep" })
+    }, [finishEdit])
+
+    const getPointing = useCallback((): boolean => pointingTarget() !== null, [pointingTarget])
+
+    const togglePointingArm = useCallback((): boolean => {
+        const p = paramsRef.current
+        // 能力 / セッションが無ければ F2 に意味は無い — false でキーを素通しさせる (v0.7 恒等)
+        if (p.adapter.getCellFormula === undefined || sessionRef.current === null) {
+            return false
+        }
+        pointingArmedRef.current = !pointingArmedRef.current
+        syncPointingHint()
+        return true
+    }, [syncPointingHint])
+
+    const getReferenceCursor = useCallback((): ReferenceCursor | null => {
+        const hit = pointingTarget()
+        const session = sessionRef.current
+        if (hit === null || session === null) {
+            return null
+        }
+        // 挿入点 (トークンなし) はセッションセルが起点 = カーソル。最初の Shift+Arrow はここから
+        // レンジを張るため、伸長アンカーもセッションセルへピンしておく
+        if ("insertAt" in hit.target) {
+            pointingAnchorRef.current = session.cell
+            return { origin: session.cell, cursor: session.cell, axis: "cells" }
+        }
+        // 置換対象 = キャレット下トークン (述語と同じ走査 + 両端含む判定なので必ず見つかる — 型充足のみ)
+        const span = findReferenceAt(hit.sink.value, hit.sink.selectionStart)
+        if (span === null) {
+            return null
+        }
+        const token = span.token
+        // 伸長アンカー (§2.7 — Excel / Sheets のキーボードポインティング): 記憶したアンカーがトークンの
+        // 角に乗るなら origin はその角、cursor は対角 (Shift+Arrow が動かすのは常にアンカーの対角 —
+        // 始端固定の導出では上 / 左方向の伸長が 2 セル目で畳まれる)。乗らない (手打ちトークン /
+        // アンカー喪失) は Excel の手打ち規則どおり始端を採用。採用した角をここで再ピンし、以後の
+        // 伸長連鎖が同じ角に固定され続けることを構造的に保証する
+        const anchor = pointingAnchorRef.current
+        switch (token.kind) {
+            case "cell": {
+                const cell = { row: token.row, col: token.col }
+                pointingAnchorRef.current = cell
+                return { origin: cell, cursor: cell, axis: "cells" }
+            }
+            case "range": {
+                const origin = anchor !== null && (anchor.row === token.start.row || anchor.row === token.end.row) && (anchor.col === token.start.col || anchor.col === token.end.col) ? { row: anchor.row, col: anchor.col } : { row: token.start.row, col: token.start.col }
+                pointingAnchorRef.current = origin
+                return { origin, cursor: { row: origin.row === token.start.row ? token.end.row : token.start.row, col: origin.col === token.start.col ? token.end.col : token.start.col }, axis: "cells" }
+            }
+            case "column": {
+                // 列帯は行成分を持たない — セッションセルの行で座標化する (formatRangeReference は行を読まない)
+                const anchorCol = anchor !== null && (anchor.col === token.start.col || anchor.col === token.end.col) ? anchor.col : token.start.col
+                const origin = { row: session.cell.row, col: anchorCol }
+                pointingAnchorRef.current = origin
+                return { origin, cursor: { row: session.cell.row, col: anchorCol === token.start.col ? token.end.col : token.start.col }, axis: "columns" }
+            }
+            case "row": {
+                const anchorRow = anchor !== null && (anchor.row === token.start.row || anchor.row === token.end.row) ? anchor.row : token.start.row
+                const origin = { row: anchorRow, col: session.cell.col }
+                pointingAnchorRef.current = origin
+                return { origin, cursor: { row: anchorRow === token.start.row ? token.end.row : token.start.row, col: session.cell.col }, axis: "rows" }
+            }
+        }
+    }, [pointingTarget])
+
+    const insertReference = useCallback(
+        (target: CellCoord | CellRange, axis: ReferenceAxis): void => {
+            const hit = pointingTarget()
+            if (hit === null) {
+                return
+            }
+            const text = formatRangeReference(target, axis)
+            const { sink } = hit
+            // { replace } は区間置換、{ insertAt } は挿入 — どちらもキャレットはトークン末尾へ
+            // (次の Arrow / クリック / tick は isPointingPrefix がこのトークンを置換対象として見つける)
+            const [start, end] = "replace" in hit.target ? hit.target.replace : [hit.target.insertAt, hit.target.insertAt]
+            const value = sink.value
+            sink.value = `${value.slice(0, start)}${text}${value.slice(end)}`
+            const caret = start + text.length
+            sink.setSelectionRange(caret, caret)
+            // 座標 (非 Shift) の指しは伸長アンカーになる — レンジ置換 (Shift+Arrow / ドラッグ move) は
+            // 押下セル / 最後に指したセルを固定角のまま保つ (§2.7 — Excel / Sheets のキーボードポインティング)
+            if ("row" in target) {
+                pointingAnchorRef.current = { row: target.row, col: target.col }
+            }
+            syncPointingHint()
+        },
+        [pointingTarget, syncPointingHint],
+    )
+
+    const captureSink = useCallback((): SinkSnapshot | null => {
+        const sink = paramsRef.current.sinkRef.current
+        if (sink === null) {
+            return null
+        }
+        return { value: sink.value, selectionStart: sink.selectionStart, selectionEnd: sink.selectionEnd }
+    }, [])
+
+    const restoreSink = useCallback(
+        (snapshot: SinkSnapshot): void => {
+            const sink = paramsRef.current.sinkRef.current
+            if (sink === null) {
+                return
+            }
+            sink.value = snapshot.value
+            sink.setSelectionRange(snapshot.selectionStart, snapshot.selectionEnd)
+            // ドラッグ押下が設定したアンカーは復元した綴りには属さない — 手打ちトークン規則 (始端) へ畳む
+            pointingAnchorRef.current = null
+            syncPointingHint()
+        },
+        [syncPointingHint],
+    )
+
+    const cycleAnchorAtCaret = useCallback((): boolean => {
+        const p = paramsRef.current
+        const sink = p.sinkRef.current
+        // 能力分岐: getCellFormula 未宣言なら "=" 始まりの文字列も数式ではない (F4 は素通し — v0.7 恒等)
+        if (p.adapter.getCellFormula === undefined || sessionRef.current === null || sink === null) {
+            return false
+        }
+        const next = cycleAnchorAt(sink.value, sink.selectionStart)
+        if (next === null) {
+            return false
+        }
+        sink.value = next.text
+        sink.setSelectionRange(next.caret, next.caret)
+        syncPointingHint()
+        return true
+    }, [syncPointingHint])
+
+    const insertAtCaret = useCallback(
+        (text: string): void => {
+            const sink = paramsRef.current.sinkRef.current
+            if (sessionRef.current === null || sink === null) {
+                return
+            }
+            // 選択区間を置換しキャレットを挿入文字列の直後へ
+            const start = sink.selectionStart
+            const end = sink.selectionEnd
+            sink.value = `${sink.value.slice(0, start)}${text}${sink.value.slice(end)}`
+            const caret = start + text.length
+            sink.setSelectionRange(caret, caret)
+            // 挿入文字列はトークンを閉じる — 伸長アンカーも畳む (印字入力と同じ規則)
+            pointingAnchorRef.current = null
+            syncPointingHint()
+        },
+        [syncPointingHint],
+    )
+
+    const getSessionText = useCallback((): string | null => {
+        const sink = paramsRef.current.sinkRef.current
+        return sessionRef.current === null || sink === null ? null : sink.value
+    }, [])
+
+    const refreshPaint = useCallback((): void => {
+        const p = paramsRef.current
+        const session = sessionRef.current
+        const sink = p.sinkRef.current
+        if (session === null || sink === null) {
+            return
+        }
+        // 旧塗りを退役してから再解決 (書式トグルで消えたキーを残さない)
+        retirePaint(sink)
+        applyPaint(sink, session.cell)
+        p.repaintOverlay?.()
+    }, [retirePaint, applyPaint])
+
+    const { enabled, sinkRef } = params
+    useEffect(() => {
+        const sink = sinkRef.current
+        if (!enabled || sink === null) {
+            return
+        }
+        const onCompositionStart = () => {
+            isComposingRef.current = true
+        }
+        const onCompositionEnd = () => {
+            isComposingRef.current = false
+        }
+        const onFocusOut = (event: FocusEvent) => {
+            const p = paramsRef.current
+            // requestCommit の blur 経路と二重 commit しない (§6.7.1 suppressFocusoutCommit)
+            if (suppressFocusoutCommitRef.current || sessionRef.current === null) {
+                return
+            }
+            const root = p.rootRef.current
+            const related = event.relatedTarget
+            // root 内への移動 (シンク⇄root の Escape 脱出等) は無視 — グリッド外または null のみ発動
+            if (root !== null && related instanceof Node && root.contains(related)) {
+                return
+            }
+            // グリッド外 focusout: 現在値を確定して idle へ (Sheets 準拠 — §6.6.1 注記)。成功時は
+            // rearm しない — フォーカスはユーザーが選んだ外部要素に残し、次のグリッド再進入 (§10-4)
+            // が rearm する。拒否時 (applyEdits throw) は onReject: "discard" が finishEdit 内で
+            // セッション破棄 + フォーカス中立の再武装まで一括で担う (呼び手側の後始末は持たない)
+            finishEdit({ rearm: false, commit: true, onReject: "discard" })
+        }
+        // ポインティングヒント (§2.7): input と document の selectionchange の後に書く (漸進的 —
+        // 判断は各判断点の述語再評価が担うため、selectionchange 非対応環境でも動作は変わらない)
+        const onInput = () => {
+            const p = paramsRef.current
+            // 印字の到着はトークンを閉じる / 手で書き換える — 伸長アンカーも畳む (手打ちトークンは
+            // Excel の手打ち規則どおり始端アンカーへ)
+            pointingAnchorRef.current = null
+            // 契機の入力で武装 (§2.7 — Sheets の演算子契機 / Excel の Enter モード): 能力 + セッション中で、
+            // まだ非武装のとき、この入力がキャレットを契機の直後に置いたなら true (以後 F2 / 終了まで保持)
+            if (p.adapter.getCellFormula !== undefined && sessionRef.current !== null && !pointingArmedRef.current && isTriggerInput(sink.value, sink.selectionStart)) {
+                pointingArmedRef.current = true
+            }
+            syncPointingHint()
+        }
+        const onSelectionChange = () => {
+            if (sessionRef.current !== null) {
+                syncPointingHint()
+            }
+        }
+        sink.addEventListener("compositionstart", onCompositionStart)
+        sink.addEventListener("compositionend", onCompositionEnd)
+        sink.addEventListener("focusout", onFocusOut)
+        sink.addEventListener("input", onInput)
+        document.addEventListener("selectionchange", onSelectionChange)
+        return () => {
+            sink.removeEventListener("compositionstart", onCompositionStart)
+            sink.removeEventListener("compositionend", onCompositionEnd)
+            sink.removeEventListener("focusout", onFocusOut)
+            sink.removeEventListener("input", onInput)
+            document.removeEventListener("selectionchange", onSelectionChange)
+        }
+    }, [enabled, sinkRef, finishEdit, syncPointingHint])
+
+    return useMemo(
+        () => ({
+            isEditing: () => sessionRef.current !== null,
+            getEditingMode: () => sessionRef.current?.mode ?? null,
+            /** True only inside requestCommit's composition-confirming blur — that focusout is internal (focus returns to the sink right after), not a grid exit. / requestCommit の composition 確定 blur の間だけ true (内部 focusout — 直後にシンクへ戻る。グリッド脱出ではない)。 */
+            isFocusoutSuppressed: () => suppressFocusoutCommitRef.current,
+            requestCommit,
+            cancelEdit,
+            startEdit,
+            getPointing,
+            togglePointingArm,
+            getReferenceCursor,
+            insertReference,
+            captureSink,
+            restoreSink,
+            cycleAnchorAtCaret,
+            insertAtCaret,
+            getSessionText,
+            refreshPaint,
+            editing,
+        }),
+        [requestCommit, cancelEdit, startEdit, getPointing, togglePointingArm, getReferenceCursor, insertReference, captureSink, restoreSink, cycleAnchorAtCaret, insertAtCaret, getSessionText, refreshPaint, editing],
+    )
+}