@aiquants/spreadsheet 0.8.0

package/src/keyboard/shortcuts.ts

@@ -0,0 +1,718 @@
+/**
+ * @fileoverview Rebindable command table (v0.8 ADR-17 — plan §1.5 / §2.6 / §4.1.11). Pure,
+ * React-free: the SpreadsheetCommand vocabulary, the canonical chord grammar
+ * (`Ctrl+Alt+Shift+KEY` — used modifiers only, fixed order, Cmd = Ctrl), the ONE table of exact
+ * built-in rows (BUILTIN_ROWS — every non-rebindable row of spec 04 §3.2 plus every rebindable
+ * command default row), the constants derived from that table (DEFAULT_SHORTCUTS,
+ * SPREADSHEET_RESERVED_SHORTCUTS, EDITING_COLUMN_COMMANDS), the VK rule that maps a keydown to a
+ * KEY token independently of the keyboard layout (letters by `event.key` when it is a single
+ * Latin letter, otherwise by the `event.code` letter; digits / punctuation / function keys always
+ * by code), strict chord matching with the AltGraph refusal (a row containing Alt is never
+ * claimed by a real AltGr press), the column-aware consumer validation (merge = REPLACE per
+ * command; every invalid input is a RangeError — fail-fast on the API surface) and the O(1)
+ * runtime resolution of one keydown to a command.
+ *
+ * 再バインド可能コマンド表 (v0.8 ADR-17 — 計画 §1.5 / §2.6 / §4.1.11)。純関数・React 非依存:
+ * SpreadsheetCommand の語彙、正準チョード文法 (`Ctrl+Alt+Shift+KEY` — 使う修飾だけ・順序固定・
+ * Cmd = Ctrl)、正確な組込み行の単一表 (BUILTIN_ROWS — spec 04 §3.2 の非再バインド行全件 +
+ * 再バインド可コマンドの既定行全件)、そこから導出する定数 (DEFAULT_SHORTCUTS /
+ * SPREADSHEET_RESERVED_SHORTCUTS / EDITING_COLUMN_COMMANDS)、keydown をレイアウト非依存の KEY
+ * トークンへ写す VK 規則 (文字は `event.key` が単一ラテン文字ならそれ、そうでなければ
+ * `event.code` の文字。数字 / 記号 / 機能キーは常に code)、AltGraph 拒否つきの厳密チョード照合
+ * (Alt を含む行は実 AltGr 押下で決して成立しない)、列を意識した consumer 検証 (merge = コマンド毎
+ * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンド解決。
+ */
+
+/**
+ * Every rebindable command of the grid (camelCase — the exact plan §1.5 list). The first block
+ * carries Google-Sheets-parity defaults; the extension block is unbound by default (`[]`) and
+ * exists so a consumer can bind it through `shortcuts`.
+ * グリッドの再バインド可能コマンド全件 (camelCase — 計画 §1.5 の正確な一覧)。前半は Google Sheets
+ * 同等の既定束縛、拡張ブロックは既定未束縛 (`[]`) で consumer が `shortcuts` で束縛するための存在。
+ */
+export type SpreadsheetCommand =
+    // Sheets 既定束縛
+    | "bold"
+    | "italic"
+    | "underline"
+    | "strikethrough"
+    | "clearFormatting"
+    | "alignLeft"
+    | "alignCenter"
+    | "alignRight"
+    | "formatNumber"
+    | "formatTime"
+    | "formatDate"
+    | "formatCurrency"
+    | "formatPercent"
+    | "formatScientific"
+    | "bordersOuter"
+    | "bordersClear"
+    | "borderTop"
+    | "borderRight"
+    | "borderBottom"
+    | "borderLeft"
+    | "insertLink"
+    | "insertNote"
+    | "insertComment"
+    | "openHyperlink"
+    | "openValidationList"
+    | "pasteSpecial"
+    | "fillDown"
+    | "fillRight"
+    | "fillSelection"
+    | "insertDate"
+    | "insertTime"
+    | "hideRows"
+    | "hideColumns"
+    | "unhideRows"
+    | "unhideColumns"
+    // 拡張コマンド (既定 [] = 未束縛、再バインド可)
+    | "formatGeneral"
+    | "bordersAll"
+    | "pasteFormats"
+    | "pasteFormulas"
+    | "pasteAdd"
+    | "pasteSubtract"
+    | "pasteMultiply"
+    | "pasteDivide"
+    | "multiplyBy100"
+    | "multiplyBy1000"
+    | "divideBy100"
+    | "divideBy1000"
+    | "signReversal"
+    | "fillColorYellow"
+    | "fillColorBlue"
+    | "fillColorGreen"
+    | "fillColorRed"
+    | "fillColorCustom1"
+    | "fillColorCustom2"
+    | "fillColorCustom3"
+    | "fillColorCustom4"
+    | "fillColorCustom5"
+    | "fontColorYellow"
+    | "fontColorBlue"
+    | "fontColorGreen"
+    | "fontColorRed"
+    | "fontColorCustom1"
+    | "fontColorCustom2"
+    | "fontColorCustom3"
+    | "fontColorCustom4"
+    | "fontColorCustom5"
+    | "toggleRowHighlight"
+    | "toggleColumnHighlight"
+    | "toggleBothHighlight"
+    | "toggleIntersectionHighlight"
+
+/**
+ * The command vocabulary as an ordered runtime list (declaration order = the order validation
+ * reports and DEFAULT_SHORTCUTS enumerates). Parity with the SpreadsheetCommand union is pinned
+ * both ways by the spec's non-distributive type guards.
+ * コマンド語彙の順序つき実行時一覧 (宣言順 = 検証の報告順 = DEFAULT_SHORTCUTS の列挙順)。
+ * SpreadsheetCommand union との一致は spec の非分配型ガードが両方向で固定。
+ */
+export const SPREADSHEET_COMMANDS: readonly SpreadsheetCommand[] = [
+    "bold",
+    "italic",
+    "underline",
+    "strikethrough",
+    "clearFormatting",
+    "alignLeft",
+    "alignCenter",
+    "alignRight",
+    "formatNumber",
+    "formatTime",
+    "formatDate",
+    "formatCurrency",
+    "formatPercent",
+    "formatScientific",
+    "bordersOuter",
+    "bordersClear",
+    "borderTop",
+    "borderRight",
+    "borderBottom",
+    "borderLeft",
+    "insertLink",
+    "insertNote",
+    "insertComment",
+    "openHyperlink",
+    "openValidationList",
+    "pasteSpecial",
+    "fillDown",
+    "fillRight",
+    "fillSelection",
+    "insertDate",
+    "insertTime",
+    "hideRows",
+    "hideColumns",
+    "unhideRows",
+    "unhideColumns",
+    "formatGeneral",
+    "bordersAll",
+    "pasteFormats",
+    "pasteFormulas",
+    "pasteAdd",
+    "pasteSubtract",
+    "pasteMultiply",
+    "pasteDivide",
+    "multiplyBy100",
+    "multiplyBy1000",
+    "divideBy100",
+    "divideBy1000",
+    "signReversal",
+    "fillColorYellow",
+    "fillColorBlue",
+    "fillColorGreen",
+    "fillColorRed",
+    "fillColorCustom1",
+    "fillColorCustom2",
+    "fillColorCustom3",
+    "fillColorCustom4",
+    "fillColorCustom5",
+    "fontColorYellow",
+    "fontColorBlue",
+    "fontColorGreen",
+    "fontColorRed",
+    "fontColorCustom1",
+    "fontColorCustom2",
+    "fontColorCustom3",
+    "fontColorCustom4",
+    "fontColorCustom5",
+    "toggleRowHighlight",
+    "toggleColumnHighlight",
+    "toggleBothHighlight",
+    "toggleIntersectionHighlight",
+]
+
+/** Command → canonical chords (empty = unbound; several chords allowed). / コマンド → 正準チョード群 (空 = 未束縛、複数可)。 */
+export type ShortcutMap = { readonly [K in SpreadsheetCommand]: readonly string[] }
+
+/**
+ * Consumer overrides: an array REPLACES the command's default list, `null` unbinds it, an absent
+ * key keeps the default. A single string is a RangeError (never silently wrapped).
+ * consumer の上書き: 配列はそのコマンドの既定一覧を置換、`null` は未束縛、キー不在は既定維持。
+ * 単一 string は RangeError (黙って 1 要素配列に包まない)。
+ */
+export type ShortcutOverrides = { readonly [K in SpreadsheetCommand]?: readonly string[] | null }
+
+/** Keymap column(s) a row is consulted in. / 行が参照されるキーマップ列。 */
+export type BuiltinColumn = "idle" | "editing" | "both"
+
+/**
+ * One row of the built-in table: an EXACT canonical chord (no families), the column(s) where the
+ * keymap has a branch for it, whether a consumer may take the chord (`rebindable: false` = the
+ * chord is reserved in that column), the command it fires (command rows only) and a
+ * documentation note.
+ * 組込み表の 1 行: 正確な正準チョード (族なし)、キーマップに分岐がある列、consumer が奪えるか
+ * (`rebindable: false` = その列で予約)、発火するコマンド (コマンド行のみ)、文書化用の一言。
+ */
+export type BuiltinRow = { readonly chord: string; readonly column: BuiltinColumn; readonly rebindable: boolean; readonly command?: SpreadsheetCommand; readonly note: string }
+
+/** A canonical chord decomposed: modifier flags + KEY token (`"A".."Z"` or a code name). / 正準チョードの分解形: 修飾フラグ + KEY トークン (`"A".."Z"` または code 名)。 */
+export type ParsedChord = { ctrl: boolean; alt: boolean; shift: boolean; key: string }
+
+/** Latin-letter KEY token (the VK rule resolves these layout-independently). / ラテン文字 KEY トークン (VK 規則がレイアウト非依存に解決)。 */
+const LETTER_TOKEN = /^[A-Z]$/
+
+/** Single Latin letter as reported by `event.key` (either case, ASCII only — `ö` / `и` / `µ` are NOT letters here). / `event.key` の単一ラテン文字 (大小いずれか・ASCII のみ — `ö` / `и` / `µ` は非該当)。 */
+const LATIN_KEY = /^[A-Za-z]$/
+
+/** `event.code` of a letter key (`KeyA`..`KeyZ`). / 文字キーの `event.code` (`KeyA`..`KeyZ`)。 */
+const LETTER_CODE = /^Key([A-Z])$/
+
+/**
+ * The closed vocabulary of non-letter KEY tokens = `KeyboardEvent.code` names of the digit,
+ * numpad, function, punctuation, navigation and editing keys. Digits are ALWAYS by code
+ * (`Digit0..9` / `Numpad0..9`) so a chord survives layouts whose digit row produces symbols
+ * (AZERTY); punctuation by code so `Ctrl+Semicolon` is the same physical key on DE (`ö`) and RU
+ * (`ж`). A token outside this set (or a lowercase letter, or a produced character such as `;`)
+ * is not canonical.
+ * 文字以外の KEY トークンの閉じた語彙 = 数字 / テンキー / 機能 / 記号 / ナビゲーション / 編集キーの
+ * `KeyboardEvent.code` 名。数字は常に code (`Digit0..9` / `Numpad0..9`) — 数字行が記号を生む
+ * レイアウト (AZERTY) でもチョードが生き残る。記号も code — `Ctrl+Semicolon` は DE (`ö`) / RU
+ * (`ж`) でも同じ物理キー。集合外のトークン (小文字・`;` 等の生成文字を含む) は非正準。
+ */
+const KEY_CODE_TOKENS: ReadonlySet<string> = new Set([
+    ...Array.from({ length: 10 }, (_, i) => `Digit${i}`),
+    ...Array.from({ length: 10 }, (_, i) => `Numpad${i}`),
+    "NumpadAdd",
+    "NumpadSubtract",
+    "NumpadMultiply",
+    "NumpadDivide",
+    "NumpadDecimal",
+    "NumpadEnter",
+    ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`),
+    "Semicolon",
+    "Quote",
+    "Comma",
+    "Period",
+    "Slash",
+    "Backslash",
+    "BracketLeft",
+    "BracketRight",
+    "Backquote",
+    "Minus",
+    "Equal",
+    "IntlYen",
+    "IntlRo",
+    "IntlBackslash",
+    "ArrowUp",
+    "ArrowDown",
+    "ArrowLeft",
+    "ArrowRight",
+    "Home",
+    "End",
+    "PageUp",
+    "PageDown",
+    "Enter",
+    "Escape",
+    "Space",
+    "Tab",
+    "Delete",
+    "Backspace",
+    "Insert",
+    "ContextMenu",
+])
+
+/** True for a canonical KEY token (`A`..`Z` or a member of KEY_CODE_TOKENS). / 正準 KEY トークンなら true (`A`..`Z` または KEY_CODE_TOKENS の要素)。 */
+const isKeyToken = (token: string): boolean => LETTER_TOKEN.test(token) || KEY_CODE_TOKENS.has(token)
+
+/**
+ * Parses a chord in canonical spelling ONLY — `[Ctrl+][Alt+][Shift+]KEY`, this order, each
+ * modifier at most once, KEY a canonical token. Anything else (lowercase, `Cmd`, a reordered or
+ * repeated modifier, a produced character, a trailing `+`, whitespace) is a RangeError: the
+ * grammar has exactly one spelling per chord so table keys compare as strings. A bare KEY is
+ * accepted here (built-in rows such as `F2` are modifier-less); the consumer-facing modifier
+ * requirement lives in validateShortcuts.
+ * 正準綴りのみのチョード解析 — `[Ctrl+][Alt+][Shift+]KEY` (この順・各修飾は高々 1 回・KEY は正準
+ * トークン)。それ以外 (小文字・`Cmd`・順序違い / 重複修飾・生成文字・末尾 `+`・空白) は RangeError:
+ * 文法はチョード 1 つに綴り 1 つで、表のキーが文字列比較で済む。素の KEY はここでは受理 (`F2`
+ * 等の組込み行は修飾なし) — consumer 向けの修飾必須は validateShortcuts が持つ。
+ */
+export const parseChord = (chord: string): ParsedChord => {
+    const parts = chord.split("+")
+    let index = 0
+    // 修飾は Ctrl → Alt → Shift の固定順で、それぞれ高々 1 回だけ消費する
+    const ctrl = parts[index] === "Ctrl"
+    if (ctrl) {
+        index += 1
+    }
+    const alt = parts[index] === "Alt"
+    if (alt) {
+        index += 1
+    }
+    const shift = parts[index] === "Shift"
+    if (shift) {
+        index += 1
+    }
+    // 残りは KEY トークン 1 個だけ (余剰 / 不足 / 順序違いの修飾は全てここで落ちる)
+    const key = parts[index]
+    if (index !== parts.length - 1 || key === undefined || !isKeyToken(key)) {
+        throw new RangeError(`[spreadsheet] shortcut ${JSON.stringify(chord)} is not canonical (expected Ctrl+Alt+Shift+KEY with used modifiers only, KEY = A-Z or a code name such as Digit1 / Semicolon / F2)`)
+    }
+    return { ctrl, alt, shift, key }
+}
+
+/** Formats a ParsedChord back to its canonical spelling (the exact inverse of parseChord). / ParsedChord を正準綴りへ戻す (parseChord の正確な逆写像)。 */
+export const formatChord = (parsed: ParsedChord): string => `${parsed.ctrl ? "Ctrl+" : ""}${parsed.alt ? "Alt+" : ""}${parsed.shift ? "Shift+" : ""}${parsed.key}`
+
+/**
+ * The VK rule (plan §2.6): maps one keydown to a KEY token independently of the layout.
+ * (a) `event.key` is a single Latin letter (any modifiers) ⇒ that letter upper-cased — so
+ * AZERTY's `Ctrl+Alt` + `{ key: "m", code: "Semicolon" }` is `M`; (b) otherwise `event.code` is
+ * `Key*` ⇒ the code letter — DE AltGr `µ`, RU `и`, macOS Option `∂` / `Dead` all resolve to the
+ * physical letter; (c) otherwise a code in the closed vocabulary ⇒ that code (digits, punctuation,
+ * function / navigation keys — always physical); (d) otherwise null (a modifier key, `Process`,
+ * `Unidentified`, IME keys).
+ * VK 規則 (計画 §2.6): keydown 1 件をレイアウト非依存の KEY トークンへ写す。(a) `event.key` が単一
+ * ラテン文字 (修飾の有無を問わない) ⇒ 大文字化 — AZERTY の `Ctrl+Alt` + `{ key: "m", code:
+ * "Semicolon" }` は `M`。(b) それ以外で `event.code` が `Key*` ⇒ その文字 — DE AltGr `µ` / RU `и` /
+ * macOS Option `∂` / `Dead` は物理文字へ。(c) それ以外で閉じた語彙内の code ⇒ その code (数字 /
+ * 記号 / 機能 / ナビゲーション — 常に物理)。(d) それ以外 null (修飾キー・`Process`・`Unidentified`・
+ * IME キー)。
+ */
+export const resolveKeyToken = (event: KeyboardEvent): string | null => {
+    // (a) 単一ラテン文字はレイアウトの生成文字を信頼する (AZERTY の M は Semicolon 位置)
+    if (LATIN_KEY.test(event.key)) {
+        return event.key.toUpperCase()
+    }
+    // (b) 非ラテン生成文字 (AltGr 記号 / キリル / macOS Option / dead key) は物理文字キーで解決
+    const letter = LETTER_CODE.exec(event.code)
+    if (letter !== null) {
+        return letter[1]
+    }
+    // (c) 数字 / 記号 / 機能キーは常に code そのもの
+    if (KEY_CODE_TOKENS.has(event.code)) {
+        return event.code
+    }
+    // (d) 修飾キー単独・IME 処理キー・未知の code
+    return null
+}
+
+/**
+ * Strict match of one keydown against a parsed chord: `ctrl = ctrlKey || metaKey` (Cmd = Ctrl),
+ * `alt`, `shift` must all equal the row's flags; the KEY token comes from resolveKeyToken. A row
+ * containing Alt is refused when `event.getModifierState("AltGraph")` is true — a real AltGr press
+ * (DE `AltGr+M` = `µ`) is character input, never a command — while the legacy ctrl+alt emulation
+ * shape (same key / code, AltGraph false) resolves through the code letter.
+ * keydown 1 件と解析済みチョードの厳密照合: `ctrl = ctrlKey || metaKey` (Cmd = Ctrl)・`alt`・`shift`
+ * が行のフラグと全て等しく、KEY トークンは resolveKeyToken。Alt を含む行は
+ * `event.getModifierState("AltGraph")` が true なら不成立 — 実 AltGr 押下 (DE `AltGr+M` = `µ`) は
+ * 文字入力であってコマンドではない。レガシーな ctrl+alt エミュレーション形状 (同じ key / code、
+ * AltGraph false) は code 文字で解決する。
+ */
+export const matchChord = (parsed: ParsedChord, event: KeyboardEvent): boolean => {
+    // 修飾は厳密一致 (Cmd は Ctrl と同一視)
+    if (parsed.ctrl !== (event.ctrlKey || event.metaKey) || parsed.alt !== event.altKey || parsed.shift !== event.shiftKey) {
+        return false
+    }
+    // Alt 行だけ AltGraph を拒否 (Ctrl+B 行は AltGraph true でも成立する)
+    if (parsed.alt && event.getModifierState("AltGraph")) {
+        return false
+    }
+    return resolveKeyToken(event) === parsed.key
+}
+
+/** Builds a non-rebindable built-in row. / 非再バインド組込み行を作る。 */
+const builtin = (chord: string, column: BuiltinColumn, note: string): BuiltinRow => ({ chord, column, rebindable: false, note })
+
+/** Builds a rebindable command default row. / 再バインド可コマンド既定行を作る。 */
+const command = (name: SpreadsheetCommand, chord: string, column: BuiltinColumn, note: string): BuiltinRow => ({ chord, column, rebindable: true, command: name, note })
+
+/** Arrow-family rows: every actual modifier row of spec 04 §3.2 (bare / Shift / Ctrl / Ctrl+Shift × 4 directions). / Arrow 族の行: spec 04 §3.2 に実在する修飾行 (素 / Shift / Ctrl / Ctrl+Shift × 4 方向)。 */
+const arrowRows = (): readonly BuiltinRow[] => {
+    const rows: BuiltinRow[] = []
+    for (const arrow of ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]) {
+        rows.push(builtin(arrow, "both", "move active (idle) / commit + move in replace mode, caret in edit mode, reference cursor while pointing"))
+        rows.push(builtin(`Shift+${arrow}`, "both", "extend selection (idle) / commit + extend in replace mode, text selection in edit mode"))
+        rows.push(builtin(`Ctrl+${arrow}`, "both", "data-edge jump (idle) / native word caret (editing), Ctrl reference cursor while pointing"))
+        rows.push(builtin(`Ctrl+Shift+${arrow}`, "both", "extend to data edge (idle) / consume + no-op (editing)"))
+    }
+    return rows
+}
+
+/** Zoom token space: `Ctrl+Alt` AND `Ctrl+Alt+Shift` × 6 (Shift-independent — the root capture listener matches the produced character). / ズームトークン空間: `Ctrl+Alt` と `Ctrl+Alt+Shift` × 6 (Shift 非依存 — root capture リスナーは生成文字で照合)。 */
+const zoomRows = (): readonly BuiltinRow[] => {
+    const rows: BuiltinRow[] = []
+    for (const token of ["Equal", "Minus", "Digit0", "NumpadAdd", "NumpadSubtract", "Numpad0"]) {
+        rows.push(builtin(`Ctrl+Alt+${token}`, "both", "zoom token space (root capture listener, produced-character matching — v0.3.3 contract)"))
+        rows.push(builtin(`Ctrl+Alt+Shift+${token}`, "both", "zoom token space, Shift-independent (JIS `=` is Shift+Minus, AZERTY `0` is Shift+Digit0)"))
+    }
+    return rows
+}
+
+/**
+ * ONE table of EXACT chords (no families): every non-rebindable built-in row of spec 04 §3.2 —
+ * Arrow / Home / End / Page* per actual modifier row, Delete, Backspace, Escape, Tab, Shift+Tab,
+ * Enter, Shift+Enter, the editing Alt+Enter newline, F2, F4 (editing-column anchor cycling),
+ * Ctrl+A, Ctrl+Z / Y, Ctrl+Shift+Z, Ctrl / Shift+Space, Shift+F10, ContextMenu, the native-chord
+ * rows Ctrl+C / X / V and Ctrl+Shift+V (pasteValues arms paste options only), Ctrl+Alt+V =
+ * pasteSpecial (a command row that is NOT rebindable) and the zoom space Ctrl+Alt AND
+ * Ctrl+Alt+Shift × {Equal, Minus, Digit0, NumpadAdd, NumpadSubtract, Numpad0} — plus every
+ * rebindable command row (command set; its chords are the defaults). `column` = where the keymap
+ * has a branch for the chord (a native passthrough in a column is NOT a row of that column, so
+ * Home / End / Delete / Ctrl+A / Z / Y are idle-only while Arrow / Enter / Tab / Page / Escape
+ * are both). Every derived constant below reads this table.
+ * 正確なチョードだけの単一表 (族なし): spec 04 §3.2 の非再バインド組込み行全件 — Arrow / Home /
+ * End / Page* の実在修飾行、Delete、Backspace、Escape、Tab、Shift+Tab、Enter、Shift+Enter、編集列の
+ * Alt+Enter 改行、F2、F4 (編集列の $ 循環)、Ctrl+A、Ctrl+Z / Y、Ctrl+Shift+Z、Ctrl / Shift+Space、
+ * Shift+F10、ContextMenu、ネイティブチョード行 Ctrl+C / X / V と Ctrl+Shift+V (pasteValues は貼付
+ * オプション武装のみ)、Ctrl+Alt+V = pasteSpecial (非再バインドのコマンド行)、ズーム空間 Ctrl+Alt
+ * および Ctrl+Alt+Shift × {Equal, Minus, Digit0, NumpadAdd, NumpadSubtract, Numpad0} — に加え、
+ * 再バインド可コマンド行全件 (command あり。そのチョードが既定)。`column` = キーマップに分岐が
+ * ある列 (ある列でのネイティブ素通しはその列の行ではない — Home / End / Delete / Ctrl+A / Z / Y
+ * は idle 限定、Arrow / Enter / Tab / Page / Escape は both)。以下の導出定数は全てこの表を読む。
+ */
+export const BUILTIN_ROWS: readonly BuiltinRow[] = [
+    ...arrowRows(),
+    builtin("Home", "idle", "row start (first visible column)"),
+    builtin("Ctrl+Home", "idle", "first visible cell"),
+    builtin("Shift+Home", "idle", "extend to row start"),
+    builtin("Ctrl+Shift+Home", "idle", "extend to first visible cell"),
+    builtin("End", "idle", "row end (last visible column)"),
+    builtin("Ctrl+End", "idle", "last visible cell"),
+    builtin("Shift+End", "idle", "extend to row end"),
+    builtin("Ctrl+Shift+End", "idle", "extend to last visible cell"),
+    builtin("PageUp", "both", "page up (idle) / commit + page up (editing)"),
+    builtin("PageDown", "both", "page down (idle) / commit + page down (editing)"),
+    builtin("Shift+PageUp", "idle", "extend one page up"),
+    builtin("Shift+PageDown", "idle", "extend one page down"),
+    builtin("Ctrl+Shift+PageUp", "idle", "consume + no-op (sheet-switch class)"),
+    builtin("Ctrl+Shift+PageDown", "idle", "consume + no-op (sheet-switch class)"),
+    builtin("Tab", "both", "cycle right (idle) / commit + cycle right (editing)"),
+    builtin("Shift+Tab", "both", "cycle left (idle) / commit + cycle left (editing)"),
+    builtin("Enter", "both", "cycle down (idle) / commit + cycle down (editing)"),
+    builtin("Shift+Enter", "both", "cycle up (idle) / commit + cycle up (editing)"),
+    builtin("Alt+Enter", "editing", "newline at the caret (editing column only — coexists with the idle openHyperlink default)"),
+    builtin("F2", "both", "start editing (idle) / toggle the pointing arm (editing)"),
+    builtin("F4", "editing", "cycle the reference anchor under the caret (formula session)"),
+    builtin("Delete", "idle", "clear every selected cell"),
+    builtin("Backspace", "idle", "clear every selected cell"),
+    builtin("Escape", "both", "abort drag > hide note tip > close rejected message > discard clip > hand off focus (idle) / cancel editing"),
+    builtin("Ctrl+A", "idle", "select all"),
+    builtin("Ctrl+Z", "idle", "undo request"),
+    builtin("Ctrl+Y", "idle", "redo request"),
+    builtin("Ctrl+Shift+Z", "idle", "redo request"),
+    builtin("Shift+F10", "idle", "keyboard context menu"),
+    builtin("ContextMenu", "idle", "keyboard context menu"),
+    builtin("Ctrl+Space", "idle", "column bands"),
+    builtin("Shift+Space", "idle", "row bands"),
+    builtin("Ctrl+C", "idle", "native copy (ClipboardEvent path — never preventDefault)"),
+    builtin("Ctrl+X", "idle", "native cut (ClipboardEvent path — never preventDefault)"),
+    builtin("Ctrl+V", "idle", "native paste (ClipboardEvent path — never preventDefault)"),
+    builtin("Ctrl+Shift+V", "idle", "pasteValues: arms the paste options, the native paste follows (not a command)"),
+    { chord: "Ctrl+Alt+V", column: "idle", rebindable: false, command: "pasteSpecial", note: "paste special (onPasteSpecialRequest / formats-only branch) — a command row that cannot be rebound" },
+    ...zoomRows(),
+    command("bold", "Ctrl+B", "both", "toggle bold"),
+    command("italic", "Ctrl+I", "both", "toggle italic"),
+    command("underline", "Ctrl+U", "both", "toggle underline"),
+    command("strikethrough", "Alt+Shift+Digit5", "both", "toggle strikethrough"),
+    command("clearFormatting", "Ctrl+Backslash", "idle", "clear formatting"),
+    command("clearFormatting", "Ctrl+IntlYen", "idle", "clear formatting (JIS ¥ key)"),
+    command("clearFormatting", "Ctrl+IntlRo", "idle", "clear formatting (JIS ろ key)"),
+    command("alignLeft", "Ctrl+Shift+L", "both", "align left"),
+    command("alignCenter", "Ctrl+Shift+E", "both", "align center"),
+    command("alignRight", "Ctrl+Shift+R", "both", "align right"),
+    command("formatNumber", "Ctrl+Shift+Digit1", "both", "number format"),
+    command("formatTime", "Ctrl+Shift+Digit2", "both", "time format"),
+    command("formatDate", "Ctrl+Shift+Digit3", "both", "date format"),
+    command("formatCurrency", "Ctrl+Shift+Digit4", "both", "currency format"),
+    command("formatPercent", "Ctrl+Shift+Digit5", "both", "percent format"),
+    command("formatScientific", "Ctrl+Shift+Digit6", "both", "scientific format"),
+    command("bordersOuter", "Alt+Shift+Digit7", "idle", "outer borders"),
+    command("bordersClear", "Alt+Shift+Digit6", "idle", "clear borders"),
+    command("borderTop", "Alt+Shift+Digit1", "idle", "top border"),
+    command("borderRight", "Alt+Shift+Digit2", "idle", "right border"),
+    command("borderBottom", "Alt+Shift+Digit3", "idle", "bottom border"),
+    command("borderLeft", "Alt+Shift+Digit4", "idle", "left border"),
+    command("insertLink", "Ctrl+K", "idle", "insert / edit hyperlink"),
+    command("insertNote", "Shift+F2", "idle", "insert / edit note"),
+    command("insertComment", "Ctrl+Alt+M", "idle", "insert comment"),
+    command("openHyperlink", "Alt+Enter", "idle", "open the hyperlink (idle column — the editing Alt+Enter row is a different column)"),
+    command("openValidationList", "Alt+ArrowDown", "idle", "open the validation list"),
+    command("fillDown", "Ctrl+D", "idle", "fill down"),
+    command("fillRight", "Ctrl+R", "idle", "fill right"),
+    command("fillSelection", "Ctrl+Enter", "both", "fill the selection with the active / session text"),
+    command("insertDate", "Ctrl+Semicolon", "both", "insert today's date (active cell / caret)"),
+    command("insertTime", "Ctrl+Shift+Semicolon", "both", "insert the current time (active cell / caret)"),
+    command("hideRows", "Ctrl+Alt+Digit9", "idle", "hide the selected rows"),
+    command("unhideRows", "Ctrl+Shift+Digit9", "idle", "unhide rows"),
+    command("unhideColumns", "Ctrl+Shift+Digit0", "idle", "unhide columns"),
+]
+
+/** True when a row is consulted in the given column (`both` covers idle and editing). / 行が指定列で参照されるなら true (`both` は idle と編集の両方)。 */
+const rowInColumn = (row: BuiltinRow, column: "idle" | "editing"): boolean => row.column === "both" || row.column === column
+
+/**
+ * Reserved chords for EVERY command: the exact chords of `rebindable: false` rows consulted in
+ * the idle column (`"idle" | "both"` — every command is consulted there). Editing-only rows
+ * (`Alt+Enter`, `F4`) are not in this list: they bind only EDITING_COLUMN_COMMANDS, which
+ * validateShortcuts checks column-aware. Families are NOT reserved — `Alt+ArrowDown`, `Alt+Enter`
+ * (idle), `Ctrl+Enter` and `Shift+F2` are valid defaults.
+ * 全コマンドに対する予約チョード: idle 列で参照される `rebindable: false` 行 (`"idle" | "both"` —
+ * 全コマンドが idle 列で参照される) の正確なチョード。編集列限定行 (`Alt+Enter`、`F4`) は含まない
+ * — EDITING_COLUMN_COMMANDS にだけ効き、validateShortcuts が列を見て検査する。族は予約しない —
+ * `Alt+ArrowDown` / `Alt+Enter` (idle) / `Ctrl+Enter` / `Shift+F2` は正当な既定。
+ */
+export const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[] = Array.from(new Set(BUILTIN_ROWS.filter((row) => !row.rebindable && rowInColumn(row, "idle")).map((row) => row.chord)))
+
+/**
+ * Commands consulted in the editing column as well as idle (every command row whose column is
+ * `editing` or `both`): fillSelection, insertDate, insertTime, bold, italic, underline,
+ * strikethrough, alignLeft / Center / Right, formatNumber .. formatScientific.
+ * idle に加え編集列でも参照されるコマンド (column が `editing` / `both` のコマンド行全件):
+ * fillSelection、insertDate、insertTime、bold、italic、underline、strikethrough、alignLeft /
+ * Center / Right、formatNumber .. formatScientific。
+ */
+export const EDITING_COLUMN_COMMANDS: ReadonlySet<SpreadsheetCommand> = new Set(BUILTIN_ROWS.filter((row) => row.command !== undefined && rowInColumn(row, "editing")).map((row) => row.command as SpreadsheetCommand))
+
+/** Commands whose row is `rebindable: false` (`pasteSpecial`) — any override is a RangeError. / 行が `rebindable: false` のコマンド (`pasteSpecial`) — 上書きは全て RangeError。 */
+const NON_REBINDABLE_COMMANDS: ReadonlySet<SpreadsheetCommand> = new Set(BUILTIN_ROWS.filter((row) => row.command !== undefined && !row.rebindable).map((row) => row.command as SpreadsheetCommand))
+
+/** Builds a complete ShortcutMap from a per-command chord reader. / コマンド毎のチョード reader から完全な ShortcutMap を組む。 */
+const buildShortcutMap = (chordsOf: (name: SpreadsheetCommand) => readonly string[]): ShortcutMap => {
+    const map: Partial<Record<SpreadsheetCommand, readonly string[]>> = {}
+    for (const name of SPREADSHEET_COMMANDS) {
+        map[name] = chordsOf(name)
+    }
+    return map as ShortcutMap
+}
+
+/**
+ * Default chords per command, derived from the `command === K` rows of BUILTIN_ROWS in table
+ * order (`[]` = unbound by default: hideColumns and every extension command). Validates under
+ * validateShortcuts(undefined) — pinned by the spec.
+ * コマンド毎の既定チョード — BUILTIN_ROWS の `command === K` 行から表順で導出 (`[]` = 既定未束縛:
+ * hideColumns と拡張コマンド全件)。validateShortcuts(undefined) を通ることを spec が固定。
+ */
+export const DEFAULT_SHORTCUTS: ShortcutMap = buildShortcutMap((name) => BUILTIN_ROWS.filter((row) => row.command === name).map((row) => row.chord))
+
+/**
+ * Chord census of a (partial) shortcut map: every chord that appears → the DISTINCT commands
+ * bound to it, in SPREADSHEET_COMMANDS order. `null` / absent entries contribute nothing; a chord
+ * repeated inside one command counts once. An entry with two or more commands is a duplicate
+ * binding (validateShortcuts condition 5); the spec pins DEFAULT_SHORTCUTS to have none.
+ * (部分) ショートカット表のチョード census: 出現する各チョード → 束縛された相異なるコマンド群
+ * (SPREADSHEET_COMMANDS 順)。`null` / 不在の項は寄与せず、同一コマンド内の重複は 1 回に数える。
+ * 2 コマンド以上の項が重複束縛 (validateShortcuts 条件 5)。DEFAULT_SHORTCUTS に重複がないことを
+ * spec が固定。
+ */
+export const censusChords = (map: ShortcutOverrides): ReadonlyMap<string, readonly SpreadsheetCommand[]> => {
+    const census = new Map<string, SpreadsheetCommand[]>()
+    for (const name of SPREADSHEET_COMMANDS) {
+        const chords = map[name]
+        // null / 不在は未束縛 = census に寄与しない
+        if (chords === null || chords === undefined) {
+            continue
+        }
+        for (const chord of chords) {
+            const bound = census.get(chord)
+            if (bound === undefined) {
+                census.set(chord, [name])
+            } else if (!bound.includes(name)) {
+                // 同一コマンド内の重複は 1 回 (別コマンドだけが重複束縛)
+                bound.push(name)
+            }
+        }
+    }
+    return census
+}
+
+/**
+ * Per-key shape validation of the overrides object (conditions 3 and the non-rebindable row):
+ * unknown command key, a value that is neither an array nor null (a single string is the
+ * documented trap — never wrapped), a non-string element, or any override of a non-rebindable
+ * command row (`pasteSpecial`) ⇒ RangeError. `undefined` values are "not overridden".
+ * overrides オブジェクトのキー毎の形検査 (条件 3 と非再バインド行): 未知のコマンドキー、配列でも
+ * null でもない値 (単一 string が文書化された罠 — 包まない)、非 string 要素、非再バインドの
+ * コマンド行 (`pasteSpecial`) への上書き ⇒ RangeError。`undefined` は「上書きなし」。
+ */
+const validateOverrideShape = (overrides: ShortcutOverrides): void => {
+    const known: ReadonlySet<string> = new Set(SPREADSHEET_COMMANDS)
+    for (const key of Object.keys(overrides)) {
+        // 型で守られていても実行時の綴り違い (blod 等) は黙って無視せず fail-fast
+        if (!known.has(key)) {
+            throw new RangeError(`[spreadsheet] shortcuts.${key} is not a SpreadsheetCommand`)
+        }
+        const value = overrides[key as SpreadsheetCommand]
+        if (value === undefined) {
+            continue
+        }
+        // 非再バインドのコマンド行は null でも配列でも上書き不可
+        if (NON_REBINDABLE_COMMANDS.has(key as SpreadsheetCommand)) {
+            throw new RangeError(`[spreadsheet] shortcuts.${key} is not rebindable`)
+        }
+        if (value === null) {
+            continue
+        }
+        // 単一 string を 1 要素配列へ包まない (配列か null のみ受理)
+        if (!Array.isArray(value)) {
+            throw new RangeError(`[spreadsheet] shortcuts.${key} must be an array or null`)
+        }
+        for (const chord of value) {
+            if (typeof chord !== "string") {
+                throw new RangeError(`[spreadsheet] shortcuts.${key} must be an array of chord strings`)
+            }
+        }
+    }
+}
+
+/**
+ * Per-chord validation for one command (conditions 1, 2 and 4): the chord must parse
+ * canonically, carry at least one modifier, and must not equal a `rebindable: false` row in ANY
+ * column where the command is consulted (idle for every command, plus editing for
+ * EDITING_COLUMN_COMMANDS) — a row that fires the command itself (`pasteSpecial`'s own row) is not
+ * a collision.
+ * コマンド 1 件のチョード毎検査 (条件 1・2・4): 正準に解析でき、修飾を 1 つ以上持ち、コマンドが
+ * 参照されるいずれかの列 (全コマンド = idle、EDITING_COLUMN_COMMANDS は編集列も) に存在する
+ * `rebindable: false` 行と等しくないこと — そのコマンド自身を発火する行 (`pasteSpecial` 自身の行)
+ * は衝突ではない。
+ */
+const validateCommandChord = (name: SpreadsheetCommand, chord: string): void => {
+    const parsed = parseChord(chord)
+    if (!(parsed.ctrl || parsed.alt || parsed.shift)) {
+        throw new RangeError(`[spreadsheet] shortcut ${chord} for ${name} has no modifier`)
+    }
+    // 列を意識した予約検査: コマンドが参照される列にある非再バインド行だけが衝突
+    const editing = EDITING_COLUMN_COMMANDS.has(name)
+    for (const row of BUILTIN_ROWS) {
+        if (row.rebindable || row.command === name || row.chord !== chord) {
+            continue
+        }
+        if (rowInColumn(row, "idle") || (editing && rowInColumn(row, "editing"))) {
+            throw new RangeError(`[spreadsheet] shortcut ${chord} for ${name} is reserved by a built-in row (${row.column} column: ${row.note})`)
+        }
+    }
+}
+
+/**
+ * Validates consumer overrides and returns the merged chord → command table. Merge = REPLACE per
+ * command over DEFAULT_SHORTCUTS (`null` / `[]` unbind; an array replaces the default list; an
+ * absent key keeps the default). RangeError, in this order: (3) a value that is a single string
+ * (or otherwise not an array / null), an unknown key, or an override of the non-rebindable
+ * `pasteSpecial`; (1) a non-canonical spelling; (2) a modifier-less chord; (4) a chord equal to a
+ * non-rebindable row in a column where the command is consulted (column-aware: `openHyperlink:
+ * ["Alt+Enter"]` is legal, `bold: ["Alt+Enter"]` collides with the editing newline row,
+ * `insertComment: ["Ctrl+Alt+V"]` collides with the pasteSpecial row, `Ctrl+Alt+Shift+Equal` is
+ * zoom space); (5) one chord bound to two commands after the merge. `undefined` validates the
+ * defaults themselves.
+ * consumer の上書きを検証し、merge 済みのチョード → コマンド表を返す。merge = DEFAULT_SHORTCUTS への
+ * コマンド毎 REPLACE (`null` / `[]` は未束縛、配列は既定一覧の置換、キー不在は既定維持)。RangeError
+ * はこの順: (3) 単一 string (または配列 / null 以外) の値・未知キー・非再バインド `pasteSpecial` の
+ * 上書き、(1) 非正準綴り、(2) 修飾なし、(4) コマンドが参照される列の非再バインド行と等しい
+ * (列を意識: `openHyperlink: ["Alt+Enter"]` は合法、`bold: ["Alt+Enter"]` は編集列の改行行と衝突、
+ * `insertComment: ["Ctrl+Alt+V"]` は pasteSpecial 行と衝突、`Ctrl+Alt+Shift+Equal` はズーム空間)、
+ * (5) merge 後に 1 チョードが 2 コマンドへ束縛。`undefined` は既定自身の検証。
+ */
+export const validateShortcuts = (overrides: ShortcutOverrides | undefined): ReadonlyMap<string, SpreadsheetCommand> => {
+    if (overrides !== undefined) {
+        validateOverrideShape(overrides)
+    }
+    // merge = REPLACE: 上書きされたコマンドは既定一覧を丸ごと置換 (union ではない)
+    const merged = buildShortcutMap((name) => {
+        const value = overrides === undefined ? undefined : overrides[name]
+        if (value === undefined) {
+            return DEFAULT_SHORTCUTS[name]
+        }
+        return value === null ? [] : value
+    })
+    // 条件 1・2・4 をコマンド順・チョード順に検査
+    for (const name of SPREADSHEET_COMMANDS) {
+        for (const chord of merged[name]) {
+            validateCommandChord(name, chord)
+        }
+    }
+    // 条件 5: merge 後の重複束縛 (census の 2 コマンド以上の項)
+    const table = new Map<string, SpreadsheetCommand>()
+    for (const [chord, commands] of censusChords(merged)) {
+        if (commands.length > 1) {
+            throw new RangeError(`[spreadsheet] shortcut ${chord} bound to ${commands.slice(0, -1).join(", ")} and ${commands[commands.length - 1]}`)
+        }
+        table.set(chord, commands[0])
+    }
+    return table
+}
+
+/**
+ * Runtime resolution for one keydown: the command whose (merged) chord matches, or null. O(1) —
+ * the event is folded to its canonical chord through the VK rule and looked up; an Alt chord
+ * under a real AltGr press (`getModifierState("AltGraph")`) is never claimed. Equivalent to
+ * "some table entry satisfies matchChord" because the grammar has one spelling per chord.
+ * keydown 1 件のコマンド解決: (merge 済み) チョードが一致するコマンド、なければ null。O(1) —
+ * event を VK 規則で正準チョードへ畳んで引く。実 AltGr 押下 (`getModifierState("AltGraph")`) の
+ * Alt チョードは決して請求しない。文法がチョード 1 つに綴り 1 つなので「表のいずれかの項が
+ * matchChord を満たす」と等価。
+ */
+export const resolveCommand = (table: ReadonlyMap<string, SpreadsheetCommand>, event: KeyboardEvent): SpreadsheetCommand | null => {
+    const key = resolveKeyToken(event)
+    if (key === null) {
+        return null
+    }
+    const alt = event.altKey
+    // 実 AltGr 押下は文字入力 — Alt チョードを請求しない (matchChord と同じ拒否)
+    if (alt && event.getModifierState("AltGraph")) {
+        return null
+    }
+    const found = table.get(formatChord({ ctrl: event.ctrlKey || event.metaKey, alt, shift: event.shiftKey, key }))
+    return found === undefined ? null : found
+}