@aiquants/spreadsheet 0.8.0

package/src/keyboard/useGridKeyboard.ts

@@ -0,0 +1,940 @@
+/**
+ * @fileoverview Grid keymap implementation on the sink's keydown (§6.6.1 contract table,
+ * idle column; editing columns delegate to the editor session in Phase 3). v0.2 adds the
+ * findDataEdge navigation with pre-dispatch fail-fast validation (§2), the Ctrl/Shift+Space
+ * band rows (§4), visible-index stepping over hidden tracks (§5.2) and the corner-based exact
+ * page arithmetic (§9). Owns the Escape priority chain, the WCAG 2.1.2 escape hand-off, the
+ * printable-key edit trigger (plain printables open eagerly on keydown — including real AltGr
+ * characters, which evergreen browsers deliver WITHOUT ctrl+alt; ctrl+alt printable shapes —
+ * legacy AltGr emulation and barren literal shortcut chords — defer the session until a real
+ * character arrives on "input", so barren chords never open a destructive empty replace
+ * session — v0.3.3), the IME timing guards and
+ * the idle-sink self-repair. Modifier matching is STRICT per the table legend — combos not
+ * listed in a row fall through untouched. v0.8 (plan §4.2.7 / ADR-17): the IME guard is the
+ * shared `isCompositionKeydown`; the merged shortcut table is consulted ONCE per column
+ * (editing column: after the pointing rows, only for EDITING_COLUMN_COMMANDS; idle column:
+ * after the drag freeze, before the Arrow rows); the editing column gains the pointing rows
+ * (Arrow / Shift+Arrow / Ctrl+Arrow move the reference cursor, F2 toggles the arm, F4 cycles
+ * the anchor) and the reference-drag freeze (Escape aborts the drag only, every other key is
+ * consumed); Delete carries `hyperlink: null` when the aspect is declared; the Escape chain
+ * gains step 0 (hide the note tip) and step 1 (close the strict-rejection message popover);
+ * Ctrl+Shift+V arms the values-only paste for the native
+ * paste event; the pointing rows also paint the pointed cell / range on the overlay's
+ * resident drag-rect node through the `onPointFrame` writer (fixed "point" mode — Excel /
+ * Sheets outline the keyboard-pointed range), extinguished by any token-closing keydown
+ * (pure chord-preparation modifiers exempt), by the arrival of a printable character
+ * (`input`) and by the sink blur — the reference drag owns the node while it is in flight.
+ * The native letter rows (Ctrl+A / Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y / Ctrl+Shift+V)
+ * are matched through the table's VK rule (`matchChord` — the produced character when it is a
+ * Latin letter, else the physical `Key*` code), so they fire on non-Latin layouts (RU / EL …)
+ * exactly like Excel / Sheets and like every command row; on Latin layouts the match is
+ * identical to the produced-character test. Every addition is a capability param — absent =
+ * the v0.7 keymap.
+ *
+ * シンク keydown 上のキーマップ実装 (§6.6.1 の契約表 — idle 列。編集列は Phase 3 の編集
+ * セッションへ委譲)。v0.2 で findDataEdge ナビゲーション + ディスパッチ前 fail-fast 検証 (§2)・
+ * Ctrl/Shift+Space の帯行 (§4)・非表示トラックの可視 index ステップ (§5.2)・隅基点の正確
+ * ページ算術 (§9) を追加。Escape 優先順・WCAG 2.1.2 脱出・印字キー編集開始 (平印字は keydown
+ * 即開始 — evergreen ブラウザの実 AltGr 印字は修飾なしで届きこちら。ctrl+alt 印字形状 =
+ * レガシー AltGr エミュレーション / 文字を生まないリテラル和音は実文字到着まで遅延 —
+ * バレン和音の空置換セッション根絶、v0.3.3)・IME
+ * タイミングガード・idle シンク自己修復を所有する。修飾は表の凡例どおり厳密一致 — 表に無い
+ * 組合せは素通し。v0.8 (計画 §4.2.7 / ADR-17): IME ガードは共有の `isCompositionKeydown`、
+ * merge 済みショートカット表は列ごとに 1 回だけ参照 (編集列: ポインティング行の後、
+ * EDITING_COLUMN_COMMANDS に限る / idle 列: ドラッグ凍結の後、Arrow 系の前)。編集列は
+ * ポインティング行 (Arrow / Shift+Arrow / Ctrl+Arrow が参照カーソル、F2 が武装トグル、F4 が
+ * $ 循環) と参照ドラッグ凍結 (Escape はドラッグだけ中断、他キーは consume) を得る。Delete は
+ * 側面宣言時に `hyperlink: null` を運び、Escape チェーンは step 0 (ノート tip 消灯) と step 1
+ * (strict 拒否 message の消灯) を得て、
+ * Ctrl+Shift+V はネイティブ paste イベント用に値のみ貼り付けを武装する。ポインティング行は
+ * 指し先セル / レンジを `onPointFrame` writer (固定 "point" モード) で overlay の常設ドラッグ
+ * 矩形ノードへも描く (Excel / Sheets のキーボード指し枠) — 消灯はトークンを閉じ得る keydown
+ * (chord 準備の純修飾キーは除く)・印字の到着 (`input`)・シンク blur で、参照ドラッグ飛行中は
+ * ドラッグ側がノードを所有する。ネイティブ文字行 (Ctrl+A /
+ * Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y / Ctrl+Shift+V) は表と同じ VK 規則 (`matchChord` — 生成文字がラテン
+ * 文字ならその文字、非ラテンは物理 `Key*` code) で照合し、非ラテン配列 (RU / EL …) でも Excel /
+ * Sheets やコマンド行と同じく成立する (ラテン配列では生成文字照合と同一)。追加は全て能力 param —
+ * 不在 = v0.7 キーマップ。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useEffect, useRef } from "react"
+import type { PasteOptions } from "../clipboard/pasteSpecial.ts"
+import type { PointingSeams } from "../editor/useCellEditor.ts"
+import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
+import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import { aspectCapabilities, type CellEdit, type EditRejection, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { colToViewportX, rowToViewportY } from "../model/frozenPartition.ts"
+import { reduceActiveCycle, type SelectionState } from "../selection/selectionState.ts"
+import { COMPOSITION_CLEAR_MS, isCompositionKeydown } from "./compositionGuard.ts"
+import { EDITING_COLUMN_COMMANDS, matchChord, parseChord, resolveCommand, type SpreadsheetCommand } from "./shortcuts.ts"
+
+/** Discriminated moveActive input (§6.6.2-3). / moveActive の判別 union 入力。 */
+export type MoveActiveInput = { mode: "cycle"; direction: SpreadsheetDirection } | { mode: "reset" | "extend"; cell: CellCoord }
+
+/**
+ * The idle column's native letter rows (BUILTIN_ROWS non-command rows), parsed once and matched
+ * with the table's `matchChord` — the VK rule of plan §2.6, so RU `Ctrl+Ф` (code KeyA) selects
+ * all and RU `Ctrl+Shift+М` / EL `Ctrl+Shift+Ω` (code KeyV) arm the values-only paste.
+ * idle 列のネイティブ文字行 (BUILTIN_ROWS の非コマンド行)。1 回だけ解析し表と同じ `matchChord`
+ * (計画 §2.6 の VK 規則) で照合する — RU の `Ctrl+Ф` (code KeyA) は全選択、RU `Ctrl+Shift+М` / EL
+ * `Ctrl+Shift+Ω` (code KeyV) は値のみ貼り付けを武装する。
+ */
+const NATIVE_LETTER_ROWS = {
+    selectAll: parseChord("Ctrl+A"),
+    undo: parseChord("Ctrl+Z"),
+    redo: parseChord("Ctrl+Y"),
+    redoShiftZ: parseChord("Ctrl+Shift+Z"),
+    pasteValues: parseChord("Ctrl+Shift+V"),
+} as const
+
+/**
+ * The command dispatch capability (ADR-17): the merged, validated chord table and the
+ * runner's execute / availability seams — one declaration, consulted once per column.
+ * コマンドディスパッチ能力 (ADR-17): merge + 検証済みチョード表と runner の execute /
+ * 利用可否シーム — 1 つの宣言として列ごとに 1 回参照する。
+ */
+export type CommandDispatch = {
+    /** validateShortcuts' result (chord → command). / validateShortcuts の結果 (チョード → コマンド)。 */
+    readonly table: ReadonlyMap<string, SpreadsheetCommand>
+    /** Runs the command; the return value is the commit result (not consulted by the keymap). / コマンド実行 (戻り値は commit 結果 — キーマップは見ない)。 */
+    readonly execute: (command: SpreadsheetCommand) => boolean
+    /** Capability gate: false = the row is absent and the chord falls through. / 能力ゲート: false = 行不在 = 素通し。 */
+    readonly isAvailable: (command: SpreadsheetCommand) => boolean
+}
+
+type UseGridKeyboardParams = {
+    /** Zoom scale reader (v0.3): the keyboard cellRect is delivered in visual px (logical × zoom) so consumers can add the pane gBCR directly. / ズーム倍率 reader (v0.3)。keyboard cellRect は視覚 px (論理 × zoom) で渡す — consumer が pane の gBCR と直接加算できる契約。 */
+    zoomRef: RefObject<number>
+    /** Rewire gate: wiring sleeps while the grid is empty and re-attaches on the non-empty transition (§6.9-1 empty branch). / 空グリッド間は結線を眠らせ、非空遷移で再結線するゲート。 */
+    enabled: boolean
+    sinkRef: RefObject<HTMLTextAreaElement | null>
+    rootRef: RefObject<HTMLElement | null>
+    /** WCAG 2.1.2 hand-off: focuses the root group as the FLAGGED Escape exit — the only in-root focus move allowed to rest on the root (Spreadsheet's onRootFocus returns every other one to the sink). / WCAG 2.1.2 脱出 — 旗つきで root を focus する (root に留まれる唯一の内部移動)。 */
+    handOffFocusToRoot: () => void
+    getSelection: () => SelectionState
+    setSelection: (next: SelectionState) => void
+    moveActive: (input: MoveActiveInput) => void
+    ensureCellVisible: (cell: CellCoord) => void
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    startEdit: (mode: "edit" | "replace") => void
+    /** The §6.9-2 write funnel (Delete / Backspace): the transaction id on success, null when the adapter rejected — the keyboard never branches on it (the wrapper already notified onEditRejected). / §6.9-2 の書込漏斗 (Delete / Backspace): 成功はトランザクション id、拒否は null — キーボードは戻り値で分岐しない (通知はラッパー側)。 */
+    commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    maxOperationCells: number
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    /** The armed clip (copy/cut) or null — Escape discard gate. / 装填中クリップ (Escape 破棄ゲート)。 */
+    getClip: () => { kind: "copy" | "cut"; range: CellRange } | null
+    discardClip: () => void
+    isDragging: () => boolean
+    abortDrag: () => void
+    /** The adapter's optional data-edge capability, re-read per keydown (adapter identity switches track naturally — §2.1). / adapter の任意データ端能力 (キーごとに読む — §2.1)。 */
+    findDataEdge: ((from: CellCoord, direction: SpreadsheetDirection) => CellCoord) | undefined
+    /** Editing mode probe — null = idle; drives the editing Arrow split (replace = commit + move, edit = native §6.6.1). / null = idle。編集列 Arrow 分岐用。 */
+    getEditingMode: () => "edit" | "replace" | null
+    /** Editing cancel, value discarded (editing Escape row). / 編集キャンセル (値破棄 — 編集列 Escape 行)。 */
+    cancelEdit: () => void
+    onUndoRequest?: () => void
+    onRedoRequest?: () => void
+    onCellContextMenu?: (cell: CellCoord, origin: { kind: "pointer"; event: MouseEvent } | { kind: "keyboard"; cellRect: { top: number; left: number; width: number; height: number } }) => void
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    handleRef: RefObject<VirtualGridHandle | null>
+    rearmSink: () => void
+    /** v0.8 capability (ADR-17): consumer-rebindable command rows. Undefined = no command rows (v0.7 keymap). / v0.8 能力 (ADR-17): 再バインド可能なコマンド行。undefined = コマンド行なし (v0.7 キーマップ)。 */
+    commands?: CommandDispatch
+    /** v0.8 capability (§2.7): the editor's pointing seams for the editing column. Undefined = no pointing rows (v0.7 editing column). / v0.8 能力 (§2.7): 編集列のポインティングシーム。undefined = ポインティング行なし (v0.7 編集列)。 */
+    pointing?: PointingSeams
+    /** v0.8 capability: the adapter whose declared aspects shape the Delete patch (`hyperlink: null` only when getCellHyperlink is declared). Undefined = text-only clear (v0.7). / v0.8 能力: Delete パッチの側面を決めるアダプタ (getCellHyperlink 宣言時だけ `hyperlink: null`)。undefined = text だけの消去 (v0.7)。 */
+    adapter?: SpreadsheetDataAdapter
+    /** v0.8 capability: Escape chain step 0 — hides the visible note tip (true = handled). Undefined = the chain starts at the clip discard (v0.7). / v0.8 能力: Escape チェーン step 0 — 可視のノート tip を消灯 (true = 処理済み)。undefined = チェーンはクリップ破棄から (v0.7)。 */
+    hideNoteTip?: () => boolean
+    /** v0.8 capability: Escape chain step 1 (after the note tip, before the clip discard) — closes the visible strict-rejection message popover (true = handled); a passive inputMessage returns false (it lives until the active cell changes). Undefined = the chain proceeds (v0.7). / v0.8 能力: Escape チェーン step 1 (ノート tip の後・クリップ破棄の前) — strict 拒否の message ポップオーバーを消灯 (true = 処理済み)。受動 inputMessage は false (生存は active セル変化が決める)。undefined = チェーン続行 (v0.7)。 */
+    closeRejectedMessage?: () => boolean
+    /** v0.8 capability: the root-owned paste-options arm written by Ctrl+Shift+V (values only) for the native paste event; cleared on keyup / blur. Undefined = Ctrl+Shift+V passes through untouched (v0.7). / v0.8 能力: Ctrl+Shift+V (値のみ) がネイティブ paste イベント用に書く root 所有の貼り付けオプション武装。keyup / blur で解除。undefined = Ctrl+Shift+V は素通し (v0.7)。 */
+    pendingPasteOptionsRef?: RefObject<PasteOptions | null>
+    /** v0.8 capability (§2.7): the keyboard-pointing reference-rect writer — paints the pointed cell / range on the overlay's resident drag-rect node with the fixed "point" mode (the same node the reference drag paints; null hides it). Undefined = no rect (the pointing rows rewrite the reference only). / v0.8 能力 (§2.7): キーボードポインティングの参照矩形 writer — 指し先セル / レンジを overlay の常設ドラッグ矩形ノードへ固定 "point" モードで描く (参照ドラッグと同一ノード。null は消灯)。undefined = 矩形なし (ポインティング行は参照書換のみ)。 */
+    onPointFrame?: (range: CellRange | null) => void
+}
+
+/**
+ * Pure chord-preparation modifier keys: their own keydown never closes a pointed reference
+ * token, so they must not extinguish the keyboard point rect — Shift+Arrow range pointing
+ * REQUIRES pressing (and auto-repeating) Shift before the Arrow arrives.
+ * chord 準備の純修飾キー: 単独の keydown はポインティングトークンを閉じないため、キーボード
+ * 参照矩形を消してはならない — Shift+Arrow のレンジ指しは Arrow より先に Shift の押下
+ * (押しっぱなしの auto-repeat 込み) が届く。
+ */
+const MODIFIER_KEYS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph"])
+
+/** Arrow key to direction. / 矢印キー → 方向。 */
+const ARROW_DIRECTIONS: Record<string, SpreadsheetDirection> = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowDown: "down",
+    ArrowUp: "up",
+}
+
+/** Consume+no-op sheet-switch-class combos (§2.2 — the v0.1 destroying-nav set shrank to this in v0.2). / シート切替クラスの consume 対象 (v0.1 の選択破壊系は v0.2 で実装行になりここへ縮退)。 */
+const isSelectionDestroyingNav = (event: KeyboardEvent): boolean => {
+    if (!event.shiftKey || event.altKey || !(event.ctrlKey || event.metaKey)) {
+        return false
+    }
+    // Ctrl+Shift+PageUp / PageDown (シート切替クラス — D-2 継続) のみ。素通しすると native
+    // 選択操作が armed 選択を collapse し Ctrl+C が無音失敗する (ADR-3 破壊)。v0.1 で同居して
+    // いた Shift+Home / End / PageUp / PageDown 系は §2.2 の実装行が受ける
+    return event.key === "PageUp" || event.key === "PageDown"
+}
+
+/**
+ * Wires the keymap to the sink. The engine owns no keydown — the Escape drag-abort travels
+ * through this hook's abortDrag seam (§6.6.2).
+ * キーマップをシンクへ結線する。エンジンは keydown を持たず、Escape のドラッグ中断は
+ * この abortDrag シームで実現する (§6.6.2)。
+ */
+export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
+    const compositionEndedAtRef = useRef<number | null>(null)
+    const clearTimerRef = useRef<number | null>(null)
+    // ctrl+alt 印字形状の遅延開始保留 (v0.3.3): 直前 keydown が ctrl+alt 同時の 1 文字キーの
+    // ときだけ true。実文字の到着 (input) で消費、次の keydown / keyup / blur で失効する一発
+    // フラグ。現実の通過者は文字を生まないリテラル和音 (Ctrl+Alt+X 等 — 空置換セッション破壊の
+    // 根絶対象) とレガシー AltGr エミュレーション形状 — evergreen ブラウザの実 AltGr 印字は
+    // 修飾なしで届き平印字の即開始経路に入る (R3(I) 確定)
+    const altGrPendingRef = useRef(false)
+    // キーボードポインティング矩形の生存フラグ (§2.7): true = 直前のポインティング Arrow が
+    // onPointFrame で描いた矩形が残り得る (消灯は冪等 — 参照ドラッグが先に消しても無害)
+    const pointFrameLiveRef = useRef(false)
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const { enabled, sinkRef, rootRef, handleRef } = params
+    useEffect(() => {
+        const sink = sinkRef.current
+        const root = rootRef.current
+        // enabled は空グリッドの間 false — 非空遷移で deps が変わり、実 DOM が揃った後に再結線される
+        // (ref identity は不変のため、これ無しでは空マウント時の null bail が永久に固定される)
+        if (!enabled || sink === null || root === null) {
+            return
+        }
+
+        /** Extinguishes the keyboard-pointing reference rect when live (idempotent — a no-op after the reference drag already hid the node). / キーボードポインティング参照矩形の消灯 (冪等 — 参照ドラッグが既に消していても無害)。 */
+        const clearPointFrame = (): void => {
+            if (!pointFrameLiveRef.current) {
+                return
+            }
+            pointFrameLiveRef.current = false
+            paramsRef.current.onPointFrame?.(null)
+        }
+
+        /** One visible step on an axis: nextVisibleIndex, staying put when none exists (the 1-step family rule — §5.2). / 軸上の可視 1 歩 (可視なし = 動かない — 1 歩系共通規則)。 */
+        const stepVisible = (axis: AxisModel, from: number, step: 1 | -1): number => nextVisibleIndex(axis, from, step) ?? from
+
+        /** One visible arrow step from a coordinate (§5.2 — hidden runs jump in one keystroke). / 座標からの可視 1 歩 (非表示ランを 1 打鍵で跳ぶ)。 */
+        const arrowStep = (from: CellCoord, direction: SpreadsheetDirection): CellCoord => {
+            const p = paramsRef.current
+            if (direction === "left" || direction === "right") {
+                return { row: from.row, col: stepVisible(p.colAxis, from.col, direction === "right" ? 1 : -1) }
+            }
+            return { row: stepVisible(p.rowAxis, from.row, direction === "down" ? 1 : -1), col: from.col }
+        }
+
+        /** First visible index of an axis (§5.2 — an all-hidden axis fail-fasts inside indexAt). / 軸の最初の可視 index (全非表示軸は indexAt が fail-fast)。 */
+        const firstVisible = (axis: AxisModel): number => axis.indexAt(0)
+        /** Last visible index of an axis (same fail-fast trait as firstVisible). / 軸の最後の可視 index (fail-fast 特性は firstVisible と同一)。 */
+        const lastVisible = (axis: AxisModel): number => axis.indexAt(axis.totalSize() - 1)
+
+        /**
+         * The §5.3 hidden-landing rescan: forward in the travel direction first (a backward
+         * snap makes data beyond a hidden edge unreachable forever), then the nearest visible
+         * backward, else the fallback (= no move).
+         * §5.3 の非表示着地再スキャン: 進行方向優先 → 逆向き最寄り可視 → 可視なしは fallback
+         * (移動しない)。
+         */
+        const rescanAxis = (axis: AxisModel, landed: number, step: 1 | -1, fallback: number): number => {
+            if (axis.sizeOf(landed) > 0) {
+                return landed // 可視着地 — 再スキャン不要
+            }
+            // 進行方向の最寄り可視 (逆向きスナップは非表示端の先のデータを永久に不到達にする)
+            const forward = nextVisibleIndex(axis, landed, step)
+            if (forward !== null) {
+                return forward
+            }
+            // 逆向きの最寄り可視
+            const backward = nextVisibleIndex(axis, landed, step === 1 ? -1 : 1)
+            if (backward !== null) {
+                return backward
+            }
+            // 可視なし = 移動しない
+            return fallback
+        }
+
+        /** Anchor-diagonal corner of the tail range (the §6.6.2-3 extension-endpoint base — active would identity-bail from the 2nd keystroke). / anchor 対角の隅 (伸長端の基点 — active 起点は 2 打鍵目が identity bail)。 */
+        const extendCorner = (): CellCoord => {
+            const state = paramsRef.current.getSelection()
+            const range = state.ranges[state.ranges.length - 1]
+            // anchor がレンジ内部なら左上へ退化 — Ctrl+A 後の既知特性 (§6.6.2-3)
+            return {
+                row: state.anchor.row === range.startRow ? range.endRow : range.startRow,
+                col: state.anchor.col === range.startCol ? range.endCol : range.startCol,
+            }
+        }
+
+        /** Extend endpoint for Shift+Arrow: the corner stepped one VISIBLE step (§5.2 — the hidden-run lookalike dead key is what this closes). / Shift+Arrow の伸長端 = 隅の可視 1 歩。 */
+        const extendEndpoint = (direction: SpreadsheetDirection): CellCoord => arrowStep(extendCorner(), direction)
+
+        /**
+         * Ctrl+Arrow target from a base cell: the data edge (capability — validated fail-fast
+         * before dispatch §2.1) or the visible grid edge (v0.1), then the §5.3 hidden-landing
+         * rescan on the progression axis. Shared by the idle reset row and the pointing cursor.
+         * 基点セルからの Ctrl+Arrow 先: データ端 (能力 — ディスパッチ前 fail-fast 検証 §2.1) か
+         * 可視グリッド端 (v0.1)、続けて進行軸の §5.3 非表示着地再スキャン。idle の reset 行と
+         * ポインティングカーソルが共有する。
+         */
+        const dataEdgeTarget = (base: CellCoord, direction: SpreadsheetDirection): CellCoord => {
+            const p = paramsRef.current
+            const horizontal = direction === "left" || direction === "right"
+            const forwardStep: 1 | -1 = direction === "right" || direction === "down" ? 1 : -1
+            let cell: CellCoord
+            if (p.findDataEdge !== undefined) {
+                cell = p.findDataEdge({ row: base.row, col: base.col }, direction)
+                // 完全 fail-fast 検証 — moveActive へのディスパッチより前 (§2.1)。throw は
+                // ここから未捕捉で伝播させる (consumer バグの即時可視化 — 整流 catch を設けない)
+                validateDataEdge(cell, base, direction)
+            } else {
+                cell = {
+                    row: direction === "down" ? p.rowAxis.count - 1 : direction === "up" ? 0 : base.row,
+                    col: direction === "right" ? p.colAxis.count - 1 : direction === "left" ? 0 : base.col,
+                }
+            }
+            // §5.3: 進行軸の非表示着地は進行方向へ再スキャン (逆向きスナップのデッドキー閉塞)
+            return horizontal ? { row: cell.row, col: rescanAxis(p.colAxis, cell.col, forwardStep, base.col) } : { row: rescanAxis(p.rowAxis, cell.row, forwardStep, base.row), col: cell.col }
+        }
+
+        /**
+         * Full fail-fast validation of a reset-path findDataEdge return BEFORE dispatch (§2.1
+         * — No-Fallback rule 2; moveActive's clampCoord would silently absorb out-of-range
+         * values and the RangeError would never fire). Orthogonal drift is a consumer bug:
+         * Excel's Ctrl+Arrow stays on the origin row / column.
+         * reset 経路の findDataEdge 戻り値をディスパッチ前に完全 fail-fast 検証 (§2.1 —
+         * moveActive 内部の clampCoord が域外値を無音吸収するため検証はここ)。直交ドリフトは
+         * consumer バグ (Excel の Ctrl+Arrow は同一行 / 列に留まる)。
+         */
+        const validateDataEdge = (target: CellCoord, from: CellCoord, direction: SpreadsheetDirection): void => {
+            const p = paramsRef.current
+            if (!(Number.isInteger(target.row) && Number.isInteger(target.col) && target.row >= 0 && target.row < p.rowAxis.count && target.col >= 0 && target.col < p.colAxis.count)) {
+                throw new RangeError(`[spreadsheet] findDataEdge returned an out-of-grid coordinate {row: ${target.row}, col: ${target.col}} for a ${p.rowAxis.count} x ${p.colAxis.count} grid`)
+            }
+            const horizontal = direction === "left" || direction === "right"
+            if (horizontal ? target.row !== from.row : target.col !== from.col) {
+                throw new RangeError(`[spreadsheet] findDataEdge must stay on the origin ${horizontal ? "row" : "column"} (received {row: ${target.row}, col: ${target.col}} from {row: ${from.row}, col: ${from.col}})`)
+            }
+        }
+
+        /** Extend-path validation: ONLY the adopted progression-axis component (§2.1 — the orthogonal component is discarded, so it is not inspected). / extend 経路の検証 (採用する進行軸成分のみ — 直交成分は不採用のため検査しない)。 */
+        const validateDataEdgeComponent = (value: number, count: number, axisLabel: "row" | "col"): void => {
+            if (!(Number.isInteger(value) && value >= 0 && value < count)) {
+                throw new RangeError(`[spreadsheet] findDataEdge returned an out-of-axis ${axisLabel} component ${value} (count ${count})`)
+            }
+        }
+
+        /**
+         * Tab/Enter cycle with the identity-reset fallthrough (§3.4-4): reduceActiveCycle is
+         * probed directly (harmless double execution of a pure function) — identity (single
+         * 1x1 range / a full circle over duplicate ranges) falls through to a reset move, so
+         * neither shape becomes a cycling dead key. Shared by the idle and editing columns.
+         * Tab / Enter 巡回 + identity フォールスルー (§3.4-4): reduceActiveCycle を直接呼んで
+         * identity 判定 (純関数の二重実行 — 無害)。identity (単一 1×1 / 重複同一レンジ群の全周)
+         * は reset の通常移動へ — どちらの形も巡回デッドキーにならない。idle 列と編集列で共有。
+         */
+        const cycleOrReset = (cycleDirection: SpreadsheetDirection): void => {
+            const p = paramsRef.current
+            const state = p.getSelection()
+            if (reduceActiveCycle(state, cycleDirection) === state) {
+                // reset 移動は可視 1 歩 (§5.2 — 単一選択を畳む Excel の単セル Tab と同じ帰結)
+                p.moveActive({ mode: "reset", cell: arrowStep(state.active, cycleDirection) })
+                return
+            }
+            p.moveActive({ mode: "cycle", direction: cycleDirection })
+        }
+
+        /** Manual newline insertion at the caret (editing Alt+Enter — most browsers insert nothing natively). / キャレット位置へ改行を挿入 (編集列 Alt+Enter)。 */
+        const insertNewlineAtCaret = (): void => {
+            const sink = sinkRef.current
+            if (sink === null) {
+                return
+            }
+            const start = sink.selectionStart ?? sink.value.length
+            const end = sink.selectionEnd ?? start
+            sink.value = `${sink.value.slice(0, start)}\n${sink.value.slice(end)}`
+            sink.setSelectionRange(start + 1, start + 1)
+        }
+
+        /**
+         * Exact page-jump target row from a base row (§9 — the v0.1 uniform-division
+         * approximation replaced by Fenwick geometry; O(log n)). The base is the MOVING
+         * endpoint: active for reset moves, the extension corner for Shift+Page (an active
+         * base would mis-land on tall selections AND identity-bail the 2nd keystroke). The
+         * landing is structurally visible (indexAt skips zero-size tracks — §5.2).
+         * 基点行からの正確なページ移動先 (§9 — v0.1 の一様割り近似を Fenwick 幾何へ置換)。
+         * 基点は移動する端点 (reset = active、Shift 系 = 伸長隅)。着地は構造的に可視 (§5.2)。
+         */
+        const pageTargetRow = (baseRow: number, direction: "up" | "down"): number => {
+            const p = paramsRef.current
+            const viewportH = handleRef.current?.getViewportSize().height ?? -1
+            if (viewportH <= 0) {
+                // ペイン未計測 (番兵 -1 / 高さ 0) はページ幾何が定義できない — 可視 1 歩へ縮退
+                return stepVisible(p.rowAxis, baseRow, direction === "down" ? 1 : -1)
+            }
+            // indexAt は入力を [0, totalSize) へ内部クランプする — 端超過は最初 / 最後の可視行に解決
+            return p.rowAxis.indexAt(p.rowAxis.offsetOf(baseRow) + (direction === "down" ? viewportH : -viewportH))
+        }
+
+        // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: §6.6.1 キーマップ表を 1 枚の平坦 dispatch として写経した契約実装 — 表の行 = コードの分岐を 1:1 で保つことが監査可能性の根拠であり、キー別関数へ分割すると表との突合が壊れる (ADR-9: 表が契約)
+        const onKeyDown = (event: KeyboardEvent) => {
+            const p = paramsRef.current
+            // 新しい打鍵は AltGr 保留を無条件に失効させる (保留を再設定するのは末尾の AltGr 分岐のみ)
+            altGrPendingRef.current = false
+            // 冒頭ガード (§6.6.2-1): 変換中 / keyCode 229 / compositionend 直後 50 ms 窓の Enter・Escape —
+            // 判定は compositionGuard.ts の単一真実源 (ポップオーバーの keydown も同じ関数を通す)
+            if (isCompositionKeydown(event, compositionEndedAtRef.current)) {
+                return
+            }
+            const ctrl = event.ctrlKey || event.metaKey
+            const alt = event.altKey
+            const direction = ARROW_DIRECTIONS[event.key]
+            // ポインティング参照矩形の消灯不変条件 (§2.7): 純修飾キー (chord 準備) 以外の打鍵は
+            // トークンを閉じ得るため必ず消す — ポインティング Arrow 行は同一ハンドラ内で直後に
+            // 再描画する (中間フレームなし)。参照ドラッグ飛行中はドラッグ側がノードを所有するため
+            // 触らない (消灯はドラッグの cleanup が担う)。生存フラグを先に見る — 矩形の無い通常
+            // 打鍵に合成ドラッグ面の読みを足さない
+            if (pointFrameLiveRef.current && !MODIFIER_KEYS.has(event.key) && !p.isDragging()) {
+                clearPointFrame()
+            }
+
+            if (p.isEditing()) {
+                // --- 編集列 (§6.6.1 の編集中 2 列 — セッション状態は useCellEditor が所有し、
+                //     ディスパッチはこの表 1 枚に置く。表に無い組合せと「ネイティブ」行は素通し) ---
+                const editingMode = p.getEditingMode()
+                // --- 参照ドラッグ capture 中 (編集中に飛行し得るドラッグは参照ドラッグだけ — 他は commit
+                //     ゲートで開始不能): Escape はドラッグだけ中断 (トークンはドラッグ前の綴りへ復元、
+                //     セッションは残る — cancelEdit には届かない)、他キーは consume (spec 04 §3.6 / §3.7) ---
+                if (p.isDragging()) {
+                    event.preventDefault()
+                    if (event.key === "Escape" && !ctrl && !event.shiftKey && !alt) {
+                        p.abortDrag()
+                    }
+                    return
+                }
+                // --- ポインティング (数式参照 — §2.7): 述語は判断点でその場評価。Arrow / Shift+Arrow /
+                //     Ctrl+Arrow は参照カーソル (カーソルはキャレット下トークンから導出、状態なし)、F2 は
+                //     武装トグル、F4 は $ 循環。能力分岐: シーム未配線 = v0.7 編集列 ---
+                const pointing = p.pointing
+                if (pointing !== undefined) {
+                    if (direction !== undefined && !alt) {
+                        const reference = pointing.getReferenceCursor()
+                        if (reference !== null) {
+                            event.preventDefault()
+                            // Ctrl はデータ端 (idle の Ctrl+Arrow と同じ導出)、素は可視 1 歩。active は動かさない
+                            const next = ctrl ? dataEdgeTarget(reference.cursor, direction) : arrowStep(reference.cursor, direction)
+                            p.ensureCellVisible(next)
+                            // Shift はトークン起点とのレンジへ置換、素はカーソル単独
+                            pointing.insertReference(event.shiftKey ? makeRange(reference.origin, next) : next, reference.axis)
+                            // 指し先の参照矩形 (§2.7): 挿入したトークンと同じ範囲を "point" 矩形で描く
+                            // (Excel / Sheets のキーボード指し枠)。帯参照 (A:C / 2:5) は軸全域へ展開 —
+                            // トークンの意味する範囲そのもの。能力分岐: writer 未配線 = 矩形なし (参照書換のみ)
+                            if (p.onPointFrame !== undefined) {
+                                const rect = event.shiftKey ? makeRange(reference.origin, next) : makeRange(next, next)
+                                p.onPointFrame(
+                                    reference.axis === "columns"
+                                        ? makeRange({ row: 0, col: rect.startCol }, { row: p.rowAxis.count - 1, col: rect.endCol })
+                                        : reference.axis === "rows"
+                                          ? makeRange({ row: rect.startRow, col: 0 }, { row: rect.endRow, col: p.colAxis.count - 1 })
+                                          : rect,
+                                )
+                                pointFrameLiveRef.current = true
+                            }
+                            return
+                        }
+                    }
+                    if (event.key === "F2" && !ctrl && !event.shiftKey && !alt && pointing.togglePointingArm()) {
+                        event.preventDefault()
+                        return
+                    }
+                    if (event.key === "F4" && !ctrl && !event.shiftKey && !alt && pointing.cycleAnchorAtCaret()) {
+                        event.preventDefault()
+                        return
+                    }
+                }
+                // --- 編集列のコマンド (ADR-17 — EDITING_COLUMN_COMMANDS のみ: fillSelection / insertDate /
+                //     insertTime / 書式トグル / 揃え / 数値書式)。能力分岐: 表未配線 = 行不在 ---
+                const editingCommands = p.commands
+                if (editingCommands !== undefined) {
+                    const command = resolveCommand(editingCommands.table, event)
+                    if (command !== null && EDITING_COLUMN_COMMANDS.has(command) && editingCommands.isAvailable(command)) {
+                        event.preventDefault()
+                        editingCommands.execute(command)
+                        return
+                    }
+                }
+                if (direction !== undefined && !alt) {
+                    if (ctrl && event.shiftKey) {
+                        event.preventDefault() // Ctrl+Shift+Arrow: consume + no-op (全モード共通行)
+                        return
+                    }
+                    if (ctrl) {
+                        return // Ctrl+Arrow: ネイティブ単語キャレット移動 (逸脱 — Excel は確定 + ジャンプ)
+                    }
+                    if (editingMode === "replace") {
+                        // replace: 確定 + 同方向へ移動 / Shift は確定 + その方向へ拡張開始 (Excel の Enter モード)
+                        event.preventDefault()
+                        if (!p.requestCommit()) {
+                            return // applyEdits 拒否 — セッション維持 (§6.7.1)
+                        }
+                        if (event.shiftKey) {
+                            p.moveActive({ mode: "extend", cell: extendEndpoint(direction) })
+                        } else {
+                            // 可視 1 歩 (§5.2 — idle の素 Arrow と同一規則)
+                            p.moveActive({ mode: "reset", cell: arrowStep(p.getSelection().active, direction) })
+                        }
+                        return
+                    }
+                    return // edit モード: キャレット移動 / テキスト選択 (ネイティブ)
+                }
+                if (event.key === "Enter" && alt && !ctrl && !event.shiftKey) {
+                    // Alt+Enter: キャレット位置へ改行挿入 (§6.6.1 — ネイティブは無挿入のブラウザが多い)。
+                    // 修飾は厳密一致 (凡例) — Shift+Alt+Enter は表に無い = 素通し
+                    event.preventDefault()
+                    insertNewlineAtCaret()
+                    return
+                }
+                if ((event.key === "Enter" || event.key === "Tab") && !ctrl && !alt) {
+                    // 確定 + 巡回 (idle 列と同じ moveActive — cycleOrReset を共有)
+                    event.preventDefault()
+                    if (!p.requestCommit()) {
+                        return
+                    }
+                    const forward = !event.shiftKey
+                    cycleOrReset(event.key === "Tab" ? (forward ? "right" : "left") : forward ? "down" : "up")
+                    return
+                }
+                if ((event.key === "PageUp" || event.key === "PageDown") && !event.shiftKey && !ctrl && !alt) {
+                    // 確定 + 移動 (§6.6.1 — §9 の基点パラメタ化ページ算術)
+                    event.preventDefault()
+                    if (!p.requestCommit()) {
+                        return
+                    }
+                    const active = p.getSelection().active
+                    p.moveActive({ mode: "reset", cell: { row: pageTargetRow(active.row, event.key === "PageDown" ? "down" : "up"), col: active.col } })
+                    return
+                }
+                if (event.key === "Escape" && !ctrl && !event.shiftKey && !alt) {
+                    // 編集キャンセル (値破棄 — §6.6.1)
+                    event.preventDefault()
+                    p.cancelEdit()
+                    return
+                }
+                // その他 (Home / End / Delete / Ctrl+A / Z / Y / C / X / V / F2 / 印字) はネイティブへ素通し
+                return
+            }
+            if (event.defaultPrevented) {
+                return
+            }
+            // ドラッグ中の非 Escape キーは consume + no-op (§6.4.1 の state 凍結契約 — キーボード面。
+            // 矢印 / Delete / Ctrl+A 等が飛行中ドラッグの anchor や adapter を動かすと、確定矩形と
+            // 画面のドラッグ矩形が乖離し onSelectionChange の「ドラッグ中は発火しない」契約が破れる。
+            // 素通しにしない理由: native caret 操作が armed 選択を崩し、確定が identity bail した
+            // 場合に rearm されない隙間が残る。Excel 同等 (ドラッグ中の打鍵は無効)。Escape だけは
+            // 下の優先順チェーン (中断) へ流す
+            if (p.isDragging() && event.key !== "Escape") {
+                event.preventDefault()
+                return
+            }
+
+            // --- consumer claim + 組込みコマンド行 (ADR-17: merge 済み表の 1 参照 — Alt 行は AltGraph で
+            //     不成立)。ドラッグ凍結の後・Arrow 系の前。能力分岐: 表未配線 = 行不在 (v0.7 キーマップ) ---
+            const commands = p.commands
+            if (commands !== undefined) {
+                const command = resolveCommand(commands.table, event)
+                if (command !== null && commands.isAvailable(command)) {
+                    event.preventDefault()
+                    commands.execute(command)
+                    return
+                }
+            }
+
+            // --- Arrow 系 (修飾は厳密一致 — 表の凡例。Alt を含む組合せは表に無い = 素通し) ---
+            if (direction !== undefined && !alt) {
+                const horizontal = direction === "left" || direction === "right"
+                const forwardStep: 1 | -1 = direction === "right" || direction === "down" ? 1 : -1
+                if (ctrl && event.shiftKey) {
+                    // Ctrl+Shift+Arrow (§2.3): 能力あり = 混成座標走査で extend / 能力なし = 隅の
+                    // 進行軸成分を可視グリッド端へ (Ctrl+Arrow のグリッド端と対称 — 死キー非対称を作らない)
+                    event.preventDefault()
+                    const state = p.getSelection()
+                    const corner = extendCorner()
+                    let progression: number
+                    if (p.findDataEdge !== undefined) {
+                        // 走査開始 = 進行軸は隅、直交軸は active (Excel は active と同じ行 / 列で走査 — §2.3-1)
+                        const scanStart: CellCoord = horizontal ? { row: state.active.row, col: corner.col } : { row: corner.row, col: state.active.col }
+                        const target = p.findDataEdge(scanStart, direction)
+                        // 検証は採用する進行軸成分のみ — ディスパッチ前 (§2.1)
+                        progression = horizontal ? target.col : target.row
+                        validateDataEdgeComponent(progression, horizontal ? p.colAxis.count : p.rowAxis.count, horizontal ? "col" : "row")
+                        // 非表示着地は進行方向へ再スキャン (§5.2 行 8 / §5.3)
+                        progression = rescanAxis(horizontal ? p.colAxis : p.rowAxis, progression, forwardStep, horizontal ? corner.col : corner.row)
+                    } else {
+                        const axis = horizontal ? p.colAxis : p.rowAxis
+                        progression = forwardStep === 1 ? lastVisible(axis) : firstVisible(axis)
+                    }
+                    // 戻りから進行軸成分のみを採り直交軸は隅を維持 (素朴 extend は直交拡張幅を潰す — §2.3-2)。
+                    // 2 打鍵目の前進は隅の進行軸成分の更新で自然に成立 (identity bail 回避 — §2.3-3)
+                    p.moveActive({ mode: "extend", cell: horizontal ? { row: corner.row, col: progression } : { row: progression, col: corner.col } })
+                    return
+                }
+                if (ctrl) {
+                    // Ctrl+Arrow: データ端ジャンプ (能力あり — §2.1) / グリッド端 (能力なし — v0.1 従来)。
+                    // 導出は dataEdgeTarget 1 点 (検証 + §5.3 再スキャン込み — ポインティングカーソルと共有)
+                    event.preventDefault()
+                    p.moveActive({ mode: "reset", cell: dataEdgeTarget(p.getSelection().active, direction) })
+                    return
+                }
+                if (event.shiftKey) {
+                    // Shift+Arrow: anchor 起点の現在レンジ拡張 (active 不動)。ensure-visible は伸長端
+                    event.preventDefault()
+                    p.moveActive({ mode: "extend", cell: extendEndpoint(direction) })
+                    return
+                }
+                // 素の Arrow: active の可視 1 歩 + 選択リセット (§5.2 — 非表示ランを 1 打鍵で跳ぶ)
+                event.preventDefault()
+                p.moveActive({ mode: "reset", cell: arrowStep(p.getSelection().active, direction) })
+                return
+            }
+
+            // --- 選択破壊系ナビの consume (§6.6.1) ---
+            if (isSelectionDestroyingNav(event)) {
+                event.preventDefault()
+                return
+            }
+
+            // --- Tab / Enter (レンジ内巡回。1×1 は通常移動)。表の行は Tab / Shift+Tab / Enter /
+            //     Shift+Enter のみ — Ctrl / Alt を含む組合せは素通し (Alt+Enter は編集列専用の「—」) ---
+            if ((event.key === "Tab" || event.key === "Enter") && !ctrl && !alt) {
+                event.preventDefault()
+                const forward = !event.shiftKey
+                cycleOrReset(event.key === "Tab" ? (forward ? "right" : "left") : forward ? "down" : "up")
+                return
+            }
+
+            // --- Home / End (§2.2 / §5.2: 素 + Ctrl = reset 行、Shift + Ctrl+Shift = 拡張行。
+            //     端点は常に可視 index — 全非表示軸は indexAt の RangeError をそのまま throw。
+            //     Alt を含む組合せは素通し) ---
+            if (event.key === "Home" && !alt) {
+                event.preventDefault()
+                if (event.shiftKey) {
+                    // Shift+Home = 隅の行で行頭拡張 (隅行規則は F8 拡張モード同型 — 実機検証ゲート対象
+                    // §2.2) / Ctrl+Shift+Home = {最初の可視行, 最初の可視列} へ拡張
+                    const corner = extendCorner()
+                    p.moveActive({ mode: "extend", cell: { row: ctrl ? firstVisible(p.rowAxis) : corner.row, col: firstVisible(p.colAxis) } })
+                    return
+                }
+                const active = p.getSelection().active
+                p.moveActive({ mode: "reset", cell: { row: ctrl ? firstVisible(p.rowAxis) : active.row, col: firstVisible(p.colAxis) } })
+                return
+            }
+            if (event.key === "End" && !alt) {
+                event.preventDefault()
+                if (event.shiftKey) {
+                    // Shift+End = 隅の行で行末拡張 (Sheets 系 — 実 Excel は End モードトグル §10 逸脱表) /
+                    // Ctrl+Shift+End = {最後の可視行, 最後の可視列} へ拡張 (Ctrl+End と同じ逸脱系)
+                    const corner = extendCorner()
+                    p.moveActive({ mode: "extend", cell: { row: ctrl ? lastVisible(p.rowAxis) : corner.row, col: lastVisible(p.colAxis) } })
+                    return
+                }
+                const active = p.getSelection().active
+                // 逸脱: Excel の Ctrl+End は used range の右下 — 本実装は可視グリッド右下 (v0.1 逸脱の一貫継続)
+                p.moveActive({ mode: "reset", cell: { row: ctrl ? lastVisible(p.rowAxis) : active.row, col: lastVisible(p.colAxis) } })
+                return
+            }
+
+            // --- PageUp / PageDown (§9: 素 = active 基点の reset、Shift = 隅基点の拡張。
+            //     Ctrl+Shift は上の consume 行、Ctrl 単独 / Alt は表に無い = 素通し) ---
+            if ((event.key === "PageUp" || event.key === "PageDown") && !ctrl && !alt) {
+                event.preventDefault()
+                const vertical = event.key === "PageDown" ? ("down" as const) : ("up" as const)
+                if (event.shiftKey) {
+                    // 基点は移動する端点 = 隅 (active 基点は縦長選択で誤着地 + identity bail — §9)
+                    const corner = extendCorner()
+                    p.moveActive({ mode: "extend", cell: { row: pageTargetRow(corner.row, vertical), col: corner.col } })
+                    return
+                }
+                const active = p.getSelection().active
+                p.moveActive({ mode: "reset", cell: { row: pageTargetRow(active.row, vertical), col: active.col } })
+                return
+            }
+
+            // --- F2: 編集開始 (edit モード) ---
+            if (event.key === "F2" && !ctrl && !event.shiftKey && !alt) {
+                event.preventDefault()
+                p.startEdit("edit")
+                return
+            }
+
+            // --- Delete / Backspace: 全選択セルを "" (上限内で commitEdits 1 回)。表の行は素のみ —
+            //     Shift+Delete (レガシー cut) / Ctrl+Delete / Alt+Delete は表に無い = 素通し
+            //     (修飾つきを consume すると cut 意図のユーザーのデータを無言破壊する) ---
+            if ((event.key === "Delete" || event.key === "Backspace") && !ctrl && !event.shiftKey && !alt) {
+                event.preventDefault()
+                const state = p.getSelection()
+                const count = countRangeCells(state.ranges)
+                if (count > p.maxOperationCells) {
+                    p.onOperationRejected?.("delete", count, "limit")
+                    return
+                }
+                const edits: CellEdit[] = []
+                // Delete はパッチ (v0.8 §4.2.7): text を消し、getCellHyperlink 宣言時だけ hyperlink も消す
+                // (Excel: 内容の削除はリンクも外す)。未宣言側面のキーは出さない — 能力分岐 (adapter 未配線 = text のみ)
+                const clearsHyperlink = p.adapter !== undefined && aspectCapabilities(p.adapter).hyperlink
+                // enumerateRangeCells の重複排除で同一セルの二重編集を作らない (§6.2.1)
+                enumerateRangeCells(state.ranges, (cell) => {
+                    edits.push(clearsHyperlink ? { row: cell.row, col: cell.col, text: "", hyperlink: null } : { row: cell.row, col: cell.col, text: "" })
+                })
+                p.commitEdits(edits, { source: "delete" })
+                return
+            }
+
+            // --- Escape: 優先順 = ドラッグ中断 > ノート tip 消灯 > strict 拒否 message 消灯 > クリップ破棄 (copy / cut アンツ) > root へ脱出 (1 押下 1 動作) ---
+            if (event.key === "Escape") {
+                // ドラッグ中断は修飾に寛容 (意図的逸脱): Shift ドラッグ中の Escape は Shift+Escape に
+                // なるのが自然な指運びで、厳密一致だと中断を取りこぼす。安全動作のみ寛容にする
+                if (p.isDragging()) {
+                    event.preventDefault()
+                    p.abortDrag()
+                    return
+                }
+                if (ctrl || event.shiftKey || alt) {
+                    return // 表の行は素の Escape のみ — 修飾つきは素通し
+                }
+                event.preventDefault()
+                // step 0 (v0.8 §4.2.7): 可視のノート tip を消灯 (ポインタがセルを離れるまで再表示抑止) —
+                // クリップ破棄より先。能力分岐: ポップオーバー未配線ならチェーンはクリップ破棄から
+                if (p.hideNoteTip?.()) {
+                    return
+                }
+                // step 1 (v0.8): strict 拒否で残った message ポップオーバーを消灯 — クリップ破棄より先
+                // (拒否告知は最前面の作業残骸)。受動 inputMessage はシームが false を返しチェーン続行
+                // (生存は active セル変化が決める — Excel 同等)。能力分岐: 未配線 = チェーン続行 (v0.7)
+                if (p.closeRejectedMessage?.()) {
+                    return
+                }
+                if (p.getClip() !== null) {
+                    // foreign でも破棄 (どのシートからでもマーキーを消せる — R2-5)
+                    p.discardClip()
+                    return
+                }
+                // WCAG 2.1.2 脱出: 旗つきの root.focus() を 1 回呼ぶ (Spreadsheet の handOffFocusToRoot)。
+                // ❗ sink.blur() を先に呼ばない — シンク保持のまま root.focus() すると暗黙 blur で
+                // relatedTarget = シンクになり、§10-4 の再入規則が自己循環しない (先 blur だと relatedTarget
+                // null で跳ね返る)。旗は onRootFocus の迷子回収 (内部から root 自身へ着地したフォーカスは
+                // シンクへ戻す — R3 是正) に「これは脱出」と伝える唯一の手段
+                p.handOffFocusToRoot()
+                return
+            }
+
+            // --- Ctrl+A: 全選択 (active / anchor は現在位置に留まる — コーナー click とは別規則)。文字行は
+            //     表と同じ VK 規則 (matchChord — 修飾は厳密一致、生成文字がラテン文字ならその文字、非ラテンは
+            //     物理 Key* code) で照合する: RU の Ctrl+Ф も全選択 (Excel / Sheets 同等) ---
+            if (matchChord(NATIVE_LETTER_ROWS.selectAll, event)) {
+                event.preventDefault()
+                const state = p.getSelection()
+                const all: CellRange = makeRange({ row: 0, col: 0 }, { row: p.rowAxis.count - 1, col: p.colAxis.count - 1 })
+                p.setSelection({ ranges: [all], anchor: state.anchor, active: state.active })
+                return
+            }
+
+            // --- Ctrl+Z / Y (+Shift+Z): Undo / Redo 中継 (VK 規則 — RU の Ctrl+Я / Ctrl+Н も成立) ---
+            if (matchChord(NATIVE_LETTER_ROWS.undo, event)) {
+                event.preventDefault()
+                p.onUndoRequest?.()
+                return
+            }
+            if (matchChord(NATIVE_LETTER_ROWS.redo, event) || matchChord(NATIVE_LETTER_ROWS.redoShiftZ, event)) {
+                event.preventDefault()
+                p.onRedoRequest?.()
+                return
+            }
+
+            // --- Shift+F10 / ContextMenu: 先に可視化 → keyboard 起点のメニュー通知 ---
+            if ((event.key === "F10" && event.shiftKey && !ctrl && !alt) || (event.key === "ContextMenu" && !ctrl && !event.shiftKey && !alt)) {
+                event.preventDefault()
+                const active = p.getSelection().active
+                // active はスクロールで画面外に出得る — 画面外座標へメニューを出さない (§6.6.1)
+                p.ensureCellVisible(active)
+                // 両軸ともハンドルの同期読み (§7-4): ensureCellVisible 直後の cellRect は
+                // 最新位置で計算しないと横画面外からのメニュー表示が旧位置へ誤配置される
+                const handle = handleRef.current
+                const position = handle?.getScrollPosition() ?? { x: 0, y: 0 }
+                // 両軸とも読点で番兵クランプ (対称 — detached の {-1,-1} を座標へ流さない)
+                const vy = Math.max(0, position.y)
+                const hx = Math.max(0, position.x)
+                // ズーム境界 (v0.3): cellRect は視覚 px (論理 × z) — consumer は胴体ペインの
+                // gBCR (視覚 px) と直接加算して fixed 配置できる (デモ /render が参照実装)
+                const zMenu = p.zoomRef.current
+                p.onCellContextMenu?.(active, {
+                    kind: "keyboard",
+                    cellRect: {
+                        // 行 / 列とも凍結パーティション順写像 (v0.6 / v0.5 計画 §2 — 凍結軸は静的座標)
+                        top: rowToViewportY(p.rowAxis, active.row, vy, handle?.getFrozenSize().rows ?? 0) * zMenu,
+                        left: colToViewportX(p.colAxis, active.col, hx, handle?.getFrozenSize().cols ?? 0) * zMenu,
+                        width: p.colAxis.sizeOf(active.col) * zMenu,
+                        height: p.rowAxis.sizeOf(active.row) * zMenu,
+                    },
+                })
+                return
+            }
+
+            // --- Ctrl+Space / Shift+Space (§4 KB-2): 全レンジの列帯化 / 行帯化。印字キー分岐より
+            //     前に置く — idle の Shift+Space はここで v0.1 の replace 編集開始を置換する (挙動
+            //     変更 — CHANGELOG)。条件は「ctrl / shift の排他的どちらか一方」= Ctrl+Shift+Space は
+            //     表に無い組合せとして素通し (Ctrl+A で代替 — README 注記) ---
+            if (event.key === " " && !alt && ctrl !== event.shiftKey) {
+                event.preventDefault()
+                const state = p.getSelection()
+                // Excel の複数エリア Ctrl+Space は全エリアを列化する — 各レンジを帯へ置換。
+                // 重複帯は併合しない (v0.1 方針)。anchor / active 不動 (包含拡大で両不変条件は自明に維持)
+                const banded = state.ranges.map((range) => (ctrl ? makeRange({ row: 0, col: range.startCol }, { row: p.rowAxis.count - 1, col: range.endCol }) : makeRange({ row: range.startRow, col: 0 }, { row: range.endRow, col: p.colAxis.count - 1 })))
+                // 単一構築 state の setSelection 1 回 (過渡状態なし — 構造 bail が等価再打鍵を無発火化)
+                p.setSelection({ ranges: banded, anchor: state.anchor, active: state.active })
+                return
+            }
+
+            // --- Ctrl+C / X / V: 何もしない (ClipboardEvent 経由で §6.5 — preventDefault 禁止) ---
+            // --- Ctrl+Shift+V (v0.8 §4.2.7): 値のみ貼り付けを武装するだけ — preventDefault しない (ネイティブ
+            //     paste イベントが発火し useClipboard が武装を読んで消す)。keyup / blur で失効。照合は VK 規則
+            //     (RU の Ctrl+Shift+М / EL の Ctrl+Shift+Ω も武装 — 生成文字だけを見ると非ラテン配列で武装が
+            //     抜け、続く text/plain の paste が all モードで format: null を書き書式を消す)。
+            //     能力分岐: ref 未配線なら従来どおり素通し (通常貼り付け) ---
+            if (p.pendingPasteOptionsRef !== undefined && matchChord(NATIVE_LETTER_ROWS.pasteValues, event)) {
+                p.pendingPasteOptionsRef.current = { mode: "values" }
+                return
+            }
+            // --- 印字キー: 編集開始 (replace)。preventDefault しない — 打鍵をシンクへ自然流入させる ---
+            if (event.key.length === 1 && !event.metaKey && !(event.ctrlKey !== event.altKey)) {
+                // 逸脱: macOS Option+文字は alt 単独扱いで編集開始しない (README / §14)
+                if (event.ctrlKey && event.altKey) {
+                    // ctrl+alt 印字形状 (§6.6.2-4 — レガシー AltGr エミュレーションとリテラル
+                    // 和音) はセッションを開かず、実文字の到着 (input) まで保留する。文字を
+                    // 生まないバレン和音 (Ctrl+Alt+X や US 配列の Ctrl+Alt+Shift+`-` = "_" 等)
+                    // が空の置換セッションを開き、次クリックの確定で "" がコミットされてセル
+                    // 内容が破壊される経路の根絶 (R1(I) blocking — jsdom / 実機の両実測)。
+                    // evergreen ブラウザの実 AltGr 印字は修飾なしで届き本分岐を通らない。
+                    // IME が compositionstart で遅延開始するのと同型の設計
+                    altGrPendingRef.current = true
+                    return
+                }
+                // 修飾なしの印字は即開始 (§6.6.2-4) — 実文字が到着しない平印字は存在しない
+                // (dead key は key 長 > 1 で本分岐に入らない)
+                p.startEdit("replace")
+                return
+            }
+            // 表に無いキーは触らない (凡例)
+        }
+
+        const onCompositionStart = () => {
+            const p = paramsRef.current
+            if (!p.isEditing()) {
+                // IME トリガー: value = "" の設定 1 点で replace モード開始 (§6.6.2-5)
+                p.startEdit("replace")
+            }
+        }
+
+        const onCompositionEnd = (event: CompositionEvent) => {
+            compositionEndedAtRef.current = event.timeStamp
+            if (clearTimerRef.current !== null) {
+                window.clearTimeout(clearTimerRef.current)
+            }
+            // 解除は保険タイマ (setTimeout(0) はタスク境界依存でガードが先に消える — §6.6.2-1)
+            clearTimerRef.current = window.setTimeout(() => {
+                compositionEndedAtRef.current = null
+                clearTimerRef.current = null
+            }, COMPOSITION_CLEAR_MS)
+        }
+
+        const onInput = () => {
+            const p = paramsRef.current
+            // 印字の到着はポインティングトークンを構造的に閉じる (§2.7) — 参照矩形を消灯する。
+            // insertReference のプログラム的な value 代入は input を発火しないため自己消灯はない
+            clearPointFrame()
+            if (!p.isEditing()) {
+                // ctrl+alt 印字形状の遅延開始 (v0.3.3): 直前 keydown が保留対象で、かつ実文字が
+                // 実際に到着した場合だけセッションを開く。startEdit("replace") は value を "" へ戻す
+                // ため、到着値を保存してから開き復元する (即開始経路と同じ終状態)
+                if (altGrPendingRef.current) {
+                    altGrPendingRef.current = false
+                    const arrived = sink.value
+                    // 保留窓 (keydown〜keyup / blur) 内のキー由来 input は当該和音自身の挿入で、
+                    // 挿入後の value が空になることはない — 非空 = 実文字到着 (AltGr+Space の " "
+                    // も正当)。和音を押下したままのマウス由来変異 (ドロップ等) も到着扱いになる
+                    // 有界残余は R3(I) 登記 (paste は useClipboard が preventDefault し到達しない)
+                    if (arrived !== "") {
+                        p.startEdit("replace")
+                        // startEdit はドラッグ中 / シンク不在で bail し得る — 開いた場合のみ復元
+                        if (p.isEditing()) {
+                            sink.value = arrived
+                            sink.setSelectionRange(arrived.length, arrived.length)
+                            return
+                        }
+                    }
+                }
+                // idle シンク自己修復: 編集セッション外のネイティブ変異 (自動修正等) を即時復旧 (§6.6.2-4)
+                p.rearmSink()
+            }
+        }
+
+        // AltGr 保留の失効 (一発性の後ろ半分): 実文字は必ず keyup より先に input で到着する —
+        // keyup まで残った保留はバレン和音の残骸で、後続の無関係変異 (自動修正等) を誤って
+        // セッション化させないうちに消す
+        const onKeyUp = () => {
+            altGrPendingRef.current = false
+            // Ctrl+Shift+V の武装も keyup で失効 (paste イベントは keydown〜keyup の間に届く)
+            const pending = paramsRef.current.pendingPasteOptionsRef
+            if (pending !== undefined) {
+                pending.current = null
+            }
+        }
+        // フォーカス喪失も失効させる — 和音がホストのフォーカス移動ショートカットを兼ねると
+        // keyup がシンクへ戻らず保留が残留し、復帰後の無関係変異 (ドロップ / 自動修正等) を
+        // 誤ってセッション化し得る (R2(I) minor の実測)
+        const onBlur = () => {
+            altGrPendingRef.current = false
+            // 武装済みの貼り付けオプションもフォーカス喪失で失効 (次の無関係な paste へ漏らさない)
+            const pending = paramsRef.current.pendingPasteOptionsRef
+            if (pending !== undefined) {
+                pending.current = null
+            }
+            // フォーカス喪失はセッションの grid-exit 確定 (focusout) を伴い得る — キーボードの
+            // 参照矩形をフォーカス無き画面に残さない (§2.7)
+            clearPointFrame()
+        }
+
+        sink.addEventListener("keydown", onKeyDown)
+        sink.addEventListener("keyup", onKeyUp)
+        sink.addEventListener("blur", onBlur)
+        sink.addEventListener("compositionstart", onCompositionStart)
+        sink.addEventListener("compositionend", onCompositionEnd)
+        sink.addEventListener("input", onInput)
+        return () => {
+            sink.removeEventListener("keydown", onKeyDown)
+            sink.removeEventListener("keyup", onKeyUp)
+            sink.removeEventListener("blur", onBlur)
+            sink.removeEventListener("compositionstart", onCompositionStart)
+            sink.removeEventListener("compositionend", onCompositionEnd)
+            sink.removeEventListener("input", onInput)
+            if (clearTimerRef.current !== null) {
+                window.clearTimeout(clearTimerRef.current)
+            }
+            // 再結線 / アンマウントを跨いで矩形を残さない (writer リレーはノード不在なら no-op)
+            clearPointFrame()
+        }
+    }, [enabled, sinkRef, rootRef, handleRef])
+}