@aiquants/spreadsheet 0.8.0

package/src/commands/useCommands.ts

@@ -0,0 +1,946 @@
+/**
+ * @fileoverview The command runner (v0.8 §4.1.13 — ADR-17): `executeCommand` for all 70
+ * `SpreadsheetCommand` literals plus the handle's write group (`applyFormat` / `setBorders` /
+ * `setHyperlink` / `setNote` / `addComment` / `setValidation`) and the capability gate
+ * `isCommandAvailable`. One table (`COMMAND_SPECS`, exhaustive over the union — tsc proves every
+ * literal is classified) drives availability and execution. Contract:
+ * - Every selection write funnels `gateSelectionWrite` (ADR-12) → `enumerateRangeCells` → ONE
+ *   `commitEdits` with the operation's source (`format` / `calc` / `fill` / `annotate` / `edit`).
+ * - Format commands compute their patch ONCE per gesture from the ACTIVE cell's BASE format
+ *   (Excel: a mixed selection follows the active cell — design v5 "Misc") and apply it to every
+ *   selected cell through `mergeFormat`, memoised per base identity (an interned base ⇒ one
+ *   `format` object identity in the `applyEdits` argument); `mergeFormat(base, patch) === base` ⇒
+ *   no edit. `bordersAll` / `bordersClear` are constant patches; `bordersOuter` and the four
+ *   single-side presets are position-dependent (each cell's OWN sides ⊕ its targeted range-edge
+ *   sides, memoised per base × edge mask — cells off the targeted edge keep their borders and get
+ *   no edit; Excel / Sheets range-edge semantics, 分冊 08 §11). Fill / font
+ *   colour toggles compare the active BASE colour (`normalizeColor`) with the target: equal ⇒
+ *   clear on the whole selection, else set (named presets: pastel fills / pure fonts — design v3 §7).
+ * - Editing column (`EDITING_COLUMN_COMMANDS` while `isEditing()`): format toggles / aligns /
+ *   number formats write the SESSION cell only and repaint the sink (`refreshEditPaint`);
+ *   `insertDate` / `insertTime` insert at the caret; `fillSelection` runs the root validation gate
+ *   (`validateCommit`) on EVERY target cell (rules are per cell — the first strict rejection keeps
+ *   the session open and returns false, the Enter keep path) and then writes the session text to
+ *   every selected cell in ONE `applyEdits` and closes the session. Every other command commits
+ *   the session first (`requestCommit`; refusal aborts with `false`).
+ * - `insertDate` / `insertTime` idle write the ACTIVE cell only (`YYYY-MM-DD` / `HH:mm:ss` local
+ *   from the `now` seam), source `edit`, THROUGH the root validation gate (`validateCommit` on the
+ *   active cell — Excel's Ctrl+; goes through edit mode, so its commit is validated; a strict
+ *   rejection returns false without writing). Self-calc uses selfCalc.ts (formula cells only when
+ *   `getCellFormula` is declared; `null` ⇒ the cell is left alone). Fill copies text / formula
+ *   (shifted) / format / validation / hyperlink / note — comments excluded. Hide / unhide go
+ *   through `gateResizeEntries` and `resizeTracks` (non-undoable geometry). Paste commands go to
+ *   the menu path `paste(options)`; `pasteSpecial` prefers `onPasteSpecialRequest`. Popover
+ *   commands open the kind (the popover hook owns its own commit gate). Highlight toggles flip the
+ *   root-owned state through `setHighlight`.
+ * - `formatCommandAnnouncement` (opt-in) is pushed to `announce` after a successful format
+ *   command with `state` = the resulting toggle state (bold / italic / underline / strikethrough /
+ *   colour toggles) or `null` for non-toggles.
+ * - Return value: true = committed (or nothing needed writing), false = gate rejection / adapter
+ *   rejection / command unavailable / commit-gate refusal. Every callback is identity-stable
+ *   (params are read through `paramsRef`).
+ *
+ * コマンド実行器 (v0.8 §4.1.13 — ADR-17)。70 の SpreadsheetCommand 全件の executeCommand、handle の
+ * 書込群 (applyFormat / setBorders / setHyperlink / setNote / addComment / setValidation)、能力
+ * ゲート isCommandAvailable。単一表 COMMAND_SPECS (union 全件の網羅を tsc が証明) が可用性と実行の
+ * 両方を駆動する。契約: 全選択書込は gateSelectionWrite (ADR-12) → enumerateRangeCells → 1 回の
+ * commitEdits (source は format / calc / fill / annotate / edit)。書式コマンドはパッチを ACTIVE セルの
+ * BASE 書式から 1 ジェスチャ 1 回だけ計算し (Excel: 混在選択は active に従う — 設計 v5) mergeFormat を
+ * base identity 毎に memo して全セルへ適用 (intern された base ⇒ applyEdits 引数の format identity は
+ * 1 つ)、無変化 (=== base) は edit を出さない。bordersAll / bordersClear は定数パッチ、bordersOuter と
+ * 単一辺 4 プリセットは位置依存 (各セル自身の辺 ⊕ レンジ外周の該当辺、base × 辺マスクで memo — 対象辺
+ * 外のセルは罫線を保ち edit を出さない。Excel / Sheets のレンジ辺意味論 — 分冊 08 §11)。色トグルは
+ * active BASE の色 (normalizeColor) と目標を比較し、等しければ
+ * 選択全体を消去、違えば設定 (名前つきプリセットは塗り淡色 / 文字原色 — 設計 v3 §7)。編集列 (isEditing 中の EDITING_COLUMN_COMMANDS): 書式トグル / 揃え /
+ * 数値書式はセッションセルだけへ書きシンクを再塗り (refreshEditPaint)、insertDate / insertTime は
+ * キャレット挿入、fillSelection は対象セル毎に root の検証ゲート validateCommit を通し (規則はセル毎、
+ * 最初の strict 拒否はセッション維持のまま false = Enter の keep 経路) セッション文字列を全選択セルへ
+ * 1 applyEdits で書きセッションを閉じる。他コマンドは先に requestCommit (拒否で false 中断)。
+ * insertDate / insertTime の idle は
+ * ACTIVE セルだけ (ローカル YYYY-MM-DD / HH:mm:ss、now シーム)、source edit、かつ root の検証ゲート
+ * validateCommit を通す (Excel の Ctrl+; は編集モード経由で確定が検証される — strict 拒否は書込なしで
+ * false)。自己計算は selfCalc.ts
+ * (数式扱いは getCellFormula 宣言時のみ、null は不変)。fill は text / 数式 (shift) / format /
+ * validation / hyperlink / note を複製し comments は除外。hide / unhide は gateResizeEntries →
+ * resizeTracks (非 undo 幾何)。paste 系はメニュー経路 paste(options)、pasteSpecial は
+ * onPasteSpecialRequest 優先。popover 系は kind を開く (commit ゲートは popover フック自身)。強調
+ * トグルは setHighlight。formatCommandAnnouncement (opt-in) は書式コマンド成功後に announce へ
+ * (state はトグルの適用後状態、非トグルは null)。戻り値: true = commit 成功 (書くものが無い場合も)、
+ * false = ゲート拒否 / アダプタ拒否 / 不可用 / commit ゲート拒否。全コールバックは identity 安定
+ * (パラメータは paramsRef 経由で読む)。
+ */
+
+import { useCallback, useMemo, useRef } from "react"
+import type { PasteOptions } from "../clipboard/pasteSpecial.ts"
+import { fillSourceEdit, readFillSource } from "../clipboard/tiling.ts"
+import { gateResizeEntries, type ResizeEntry, ROW_FANOUT_DIVISOR, ROW_HIDDEN_LIMIT } from "../header/resizeGates.ts"
+import { EDITING_COLUMN_COMMANDS, type SpreadsheetCommand } from "../keyboard/shortcuts.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellCommentInput, normalizeAdapterHyperlink, normalizeHyperlink } from "../model/cellAnnotations.ts"
+import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import { BORDER_DEFAULT_COLOR, type CellBorder, type CellBorders, type CellFormat, type CellFormatPatch, type CellValueFormat, mergeFormat } from "../model/cellFormat.ts"
+import { normalizeColor } from "../model/cellPaint.ts"
+import type { CellEdit, EditRejection, SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import type { DataValidationRule, ValidationVerdict } from "../model/dataValidation.ts"
+import type { PopoverKind, PopoverOverrides } from "../popover/usePopovers.ts"
+import type { SelectionState } from "../selection/selectionState.ts"
+import { reverseSignFormula, reverseSignText, type ScaleExponent, scaleDecimalText, scaleFormula } from "./selfCalc.ts"
+
+/** Border preset vocabulary of `setBorders` (v0.8 §1.10). / setBorders のプリセット語彙 (v0.8 §1.10)。 */
+export type BorderPreset = "outer" | "all" | "clear" | "top" | "right" | "bottom" | "left"
+
+/** Row / column / intersection highlight state (structurally the root's HighlightState — v0.8 §1.9). / 行 / 列 / 交点の強調状態 (root の HighlightState と構造同一 — v0.8 §1.9)。 */
+export type CommandHighlightState = { row: boolean; column: boolean; intersection: boolean }
+
+/** Keyboard-origin cell rect (visual px — the onCellContextMenu shape). / キーボード起点のセル矩形 (視覚 px — onCellContextMenu と同形)。 */
+export type KeyboardCellRect = { top: number; left: number; width: number; height: number }
+
+/** The `formats` prop (currency + optional rendering locale). / `formats` prop (通貨 + 任意の描画 locale)。 */
+export type CommandFormats = { currency: string; locale?: string }
+
+export type UseCommandsParams = {
+    adapter: SpreadsheetDataAdapter
+    getSelection: () => SelectionState
+    /** The §6.9-2 wrapper: the transaction id on success, null = rejected. / §6.9-2 ラッパー (成功は transaction id、null = 拒否)。 */
+    commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    getActive: () => CellCoord
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    /** Closes the session discarding its text (fillSelection wrote it everywhere already). / セッションを値破棄で閉じる (fillSelection が全セルへ書いた後)。 */
+    cancelEdit: () => void
+    /** The live session text, null when idle. / セッション文字列 (idle は null)。 */
+    getSessionText: () => string | null
+    /** The root validation gate (分冊 08 §4.2) — the editing-column fillSelection runs it per target cell and the idle insertDate / insertTime run it on the active cell; a strict rejection is reported by the root (onValidationRejected + message popover) and comes back as ok: false. / root の検証ゲート (分冊 08 §4.2) — 編集列 fillSelection が対象セル毎に、idle の insertDate / insertTime が active セルへ呼ぶ。strict 拒否は root が通知 (onValidationRejected + message ポップオーバー) し ok: false で返る。 */
+    validateCommit: (cell: CellCoord, text: string) => ValidationVerdict
+    /** Inserts text at the sink caret (editing column insertDate / insertTime). / シンクのキャレットへ挿入 (編集列の insertDate / insertTime)。 */
+    insertAtCaret: (text: string) => void
+    /** Recomputes the sink paint after a format write on the session cell. / セッションセルの書式書込後にシンク塗りを再計算。 */
+    refreshEditPaint: () => void
+    maxOperationCells: number
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    /** Custom colour slots (5 each) for fillColorCustomN / fontColorCustomN. / fillColorCustomN / fontColorCustomN の色スロット (各 5)。 */
+    colors: { fill: readonly string[]; font: readonly string[] }
+    /** The formatCurrency currency / rendering locale; undefined ⇒ formatCurrency is unavailable (passes through). / formatCurrency の通貨 / locale。未宣言なら formatCurrency は行不在 (素通し)。 */
+    formats: CommandFormats | undefined
+    getHighlight: () => CommandHighlightState
+    setHighlight: (next: CommandHighlightState) => void
+    /** The `popovers` prop (kind availability gate). / `popovers` prop (kind の可用性ゲート)。 */
+    popovers: PopoverOverrides | undefined
+    openPopover: (kind: PopoverKind) => void
+    onHyperlinkOpen?: (url: string, cell: CellCoord) => void
+    onPasteSpecialRequest?: (origin: { kind: "keyboard"; cellRect: KeyboardCellRect }) => void
+    /** The clipboard menu path (paste-special commands). / クリップボードのメニュー経路 (paste-special 系)。 */
+    paste: (options: PasteOptions) => Promise<"applied" | "empty" | "rejected">
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    /** The batch resize seam (already-gated entries). / バッチリサイズシーム (ゲート済み entries)。 */
+    resizeTracks: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void
+    defaultRowHeight: number
+    defaultColumnWidth: number
+    /** Clock seam for insertDate / insertTime. / insertDate / insertTime の時計シーム。 */
+    now: () => number
+    announce: (text: string) => void
+    formatCommandAnnouncement?: (ctx: { command: SpreadsheetCommand; state: boolean | null }) => string
+    /** The active cell's keyboard rect (onPasteSpecialRequest origin). / active セルのキーボード矩形 (onPasteSpecialRequest の origin)。 */
+    keyboardCellRect: () => KeyboardCellRect
+}
+
+/** The handle's write group + the command entry points (v0.8 §1.10 / §4.1.13). / handle の書込群 + コマンド入口 (v0.8 §1.10 / §4.1.13)。 */
+export type CommandRunner = {
+    executeCommand: (command: SpreadsheetCommand) => boolean
+    applyFormat: (patch: CellFormatPatch) => boolean
+    setBorders: (preset: BorderPreset, border?: CellBorder) => boolean
+    setHyperlink: (url: string | null) => boolean
+    setNote: (text: string | null) => boolean
+    addComment: (input: CellCommentInput) => boolean
+    setValidation: (rule: DataValidationRule | null) => boolean
+    /** Capability gate: false = the keymap row does not exist (the chord passes through). `openHyperlink` with `onHyperlinkOpen` declared is cell-aware: the row exists only while the active cell has a link. / 能力ゲート: false = 行不在 (チョードは素通し)。`onHyperlinkOpen` 宣言時の `openHyperlink` はセル依存 — active にリンクがある間だけ行が存在する。 */
+    isCommandAvailable: (command: SpreadsheetCommand) => boolean
+}
+
+/**
+ * ADR-12 selection-write gate: count the cells, reject with "limit" over the cap.
+ * ADR-12 の選択書込ゲート: セル数を数え、上限超過は "limit" で拒否する。
+ */
+export const gateSelectionWrite = (op: SpreadsheetOperation, ranges: readonly CellRange[], max: number, reject: ((op: SpreadsheetOperation, count: number, reason: "limit") => void) | undefined): boolean => {
+    const count = countRangeCells(ranges)
+    if (count > max) {
+        reject?.(op, count, "limit")
+        return false
+    }
+    return true
+}
+
+/** Toggle keys of the four boolean format commands. / 真偽値書式コマンド 4 種のキー。 */
+type ToggleKey = "bold" | "italic" | "underline" | "strikethrough"
+
+/** The six value-format commands. / 値書式コマンド 6 種。 */
+type ValueKind = "number" | "time" | "date" | "currency" | "percent" | "scientific"
+
+/** Classification of one command (the single table both gates and dispatch consume). / コマンド 1 件の分類 (ゲートと dispatch が共用する単一表)。 */
+type CommandSpec =
+    | { kind: "toggle"; key: ToggleKey }
+    | { kind: "patch"; patch: CellFormatPatch }
+    | { kind: "clear" }
+    | { kind: "value"; value: ValueKind }
+    | { kind: "borders"; preset: BorderPreset }
+    | { kind: "color"; key: "background" | "color"; preset: string | null; custom: number | null }
+    | { kind: "calc"; exponent: ScaleExponent }
+    | { kind: "sign" }
+    | { kind: "fill"; direction: "down" | "right" | "selection" }
+    | { kind: "popover"; popover: "link" | "note" | "comment" | "list" }
+    | { kind: "openHyperlink" }
+    | { kind: "pasteSpecial" }
+    | { kind: "paste"; options: PasteOptions }
+    | { kind: "insertNow"; unit: "date" | "time" }
+    | { kind: "hide"; axis: "row" | "col"; hide: boolean }
+    | { kind: "highlight"; target: "row" | "column" | "both" | "intersection" }
+
+/** Fill presets of the four named fill-colour toggles — pastels (design v3 §7 / the reference extension: legible behind the default text colour). / 名前つき塗りトグル 4 種のプリセット — 淡色 (設計 v3 §7 / 参照拡張機能と同値: 既定文字色の背後で可読)。 */
+const FILL_PRESETS = { Yellow: "#FFFF99", Blue: "#CCFFFF", Green: "#CCFFCC", Red: "#FFCCCC" } as const
+
+/** Font presets of the four named font-colour toggles — pure primaries (design v3 §7). / 名前つき文字色トグル 4 種のプリセット — 原色 (設計 v3 §7)。 */
+const FONT_PRESETS = { Yellow: "#FFFF00", Blue: "#0000FF", Green: "#00FF00", Red: "#FF0000" } as const
+
+/** The exhaustive command table (a missing literal is a tsc error). / 網羅的コマンド表 (リテラル欠落は tsc エラー)。 */
+const COMMAND_SPECS: { readonly [K in SpreadsheetCommand]: CommandSpec } = {
+    bold: { kind: "toggle", key: "bold" },
+    italic: { kind: "toggle", key: "italic" },
+    underline: { kind: "toggle", key: "underline" },
+    strikethrough: { kind: "toggle", key: "strikethrough" },
+    clearFormatting: { kind: "clear" },
+    alignLeft: { kind: "patch", patch: { align: "left" } },
+    alignCenter: { kind: "patch", patch: { align: "center" } },
+    alignRight: { kind: "patch", patch: { align: "right" } },
+    formatNumber: { kind: "value", value: "number" },
+    formatTime: { kind: "value", value: "time" },
+    formatDate: { kind: "value", value: "date" },
+    formatCurrency: { kind: "value", value: "currency" },
+    formatPercent: { kind: "value", value: "percent" },
+    formatScientific: { kind: "value", value: "scientific" },
+    bordersOuter: { kind: "borders", preset: "outer" },
+    bordersClear: { kind: "borders", preset: "clear" },
+    borderTop: { kind: "borders", preset: "top" },
+    borderRight: { kind: "borders", preset: "right" },
+    borderBottom: { kind: "borders", preset: "bottom" },
+    borderLeft: { kind: "borders", preset: "left" },
+    insertLink: { kind: "popover", popover: "link" },
+    insertNote: { kind: "popover", popover: "note" },
+    insertComment: { kind: "popover", popover: "comment" },
+    openHyperlink: { kind: "openHyperlink" },
+    openValidationList: { kind: "popover", popover: "list" },
+    pasteSpecial: { kind: "pasteSpecial" },
+    fillDown: { kind: "fill", direction: "down" },
+    fillRight: { kind: "fill", direction: "right" },
+    fillSelection: { kind: "fill", direction: "selection" },
+    insertDate: { kind: "insertNow", unit: "date" },
+    insertTime: { kind: "insertNow", unit: "time" },
+    hideRows: { kind: "hide", axis: "row", hide: true },
+    hideColumns: { kind: "hide", axis: "col", hide: true },
+    unhideRows: { kind: "hide", axis: "row", hide: false },
+    unhideColumns: { kind: "hide", axis: "col", hide: false },
+    formatGeneral: { kind: "patch", patch: { value: null } },
+    bordersAll: { kind: "borders", preset: "all" },
+    pasteFormats: { kind: "paste", options: { mode: "formats" } },
+    pasteFormulas: { kind: "paste", options: { mode: "formulas" } },
+    pasteAdd: { kind: "paste", options: { mode: "all", operation: "add" } },
+    pasteSubtract: { kind: "paste", options: { mode: "all", operation: "subtract" } },
+    pasteMultiply: { kind: "paste", options: { mode: "all", operation: "multiply" } },
+    pasteDivide: { kind: "paste", options: { mode: "all", operation: "divide" } },
+    multiplyBy100: { kind: "calc", exponent: 2 },
+    multiplyBy1000: { kind: "calc", exponent: 3 },
+    divideBy100: { kind: "calc", exponent: -2 },
+    divideBy1000: { kind: "calc", exponent: -3 },
+    signReversal: { kind: "sign" },
+    fillColorYellow: { kind: "color", key: "background", preset: FILL_PRESETS.Yellow, custom: null },
+    fillColorBlue: { kind: "color", key: "background", preset: FILL_PRESETS.Blue, custom: null },
+    fillColorGreen: { kind: "color", key: "background", preset: FILL_PRESETS.Green, custom: null },
+    fillColorRed: { kind: "color", key: "background", preset: FILL_PRESETS.Red, custom: null },
+    fillColorCustom1: { kind: "color", key: "background", preset: null, custom: 0 },
+    fillColorCustom2: { kind: "color", key: "background", preset: null, custom: 1 },
+    fillColorCustom3: { kind: "color", key: "background", preset: null, custom: 2 },
+    fillColorCustom4: { kind: "color", key: "background", preset: null, custom: 3 },
+    fillColorCustom5: { kind: "color", key: "background", preset: null, custom: 4 },
+    fontColorYellow: { kind: "color", key: "color", preset: FONT_PRESETS.Yellow, custom: null },
+    fontColorBlue: { kind: "color", key: "color", preset: FONT_PRESETS.Blue, custom: null },
+    fontColorGreen: { kind: "color", key: "color", preset: FONT_PRESETS.Green, custom: null },
+    fontColorRed: { kind: "color", key: "color", preset: FONT_PRESETS.Red, custom: null },
+    fontColorCustom1: { kind: "color", key: "color", preset: null, custom: 0 },
+    fontColorCustom2: { kind: "color", key: "color", preset: null, custom: 1 },
+    fontColorCustom3: { kind: "color", key: "color", preset: null, custom: 2 },
+    fontColorCustom4: { kind: "color", key: "color", preset: null, custom: 3 },
+    fontColorCustom5: { kind: "color", key: "color", preset: null, custom: 4 },
+    toggleRowHighlight: { kind: "highlight", target: "row" },
+    toggleColumnHighlight: { kind: "highlight", target: "column" },
+    toggleBothHighlight: { kind: "highlight", target: "both" },
+    toggleIntersectionHighlight: { kind: "highlight", target: "intersection" },
+}
+
+/** `clearFormatting` = every CellFormat key cleared (`-?` makes a newly added key a tsc error here). / clearFormatting = CellFormat 全キーの消去 (`-?` により新キーの追加漏れは tsc エラー)。 */
+const CLEAR_PATCH: { readonly [K in keyof CellFormat]-?: null } = { value: null, align: null, verticalAlign: null, wrap: null, background: null, color: null, bold: null, italic: null, underline: null, strikethrough: null, fontFamily: null, fontSize: null, borders: null }
+
+/** Two-digit zero padding. / 2 桁ゼロ埋め。 */
+const pad2 = (n: number): string => (n < 10 ? `0${n}` : String(n))
+
+/** Local `YYYY-MM-DD` of a timestamp. / タイムスタンプのローカル YYYY-MM-DD。 */
+const formatLocalDate = (timestamp: number): string => {
+    const d = new Date(timestamp)
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+}
+
+/** Local `HH:mm:ss` of a timestamp. / タイムスタンプのローカル HH:mm:ss。 */
+const formatLocalTime = (timestamp: number): string => {
+    const d = new Date(timestamp)
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`
+}
+
+/** Edge bit mask of a cell inside its range (top 1 / right 2 / bottom 4 / left 8). / レンジ内セルの外周辺ビット (top 1 / right 2 / bottom 4 / left 8)。 */
+const edgeMaskOf = (cell: CellCoord, range: CellRange): number => (cell.row === range.startRow ? 1 : 0) | (cell.col === range.endCol ? 2 : 0) | (cell.row === range.endRow ? 4 : 0) | (cell.col === range.startCol ? 8 : 0)
+
+/** The sides a mask selects, each set to `border`. / マスクが選ぶ辺 (各辺を border に)。 */
+const sidesOfMask = (mask: number, border: CellBorder): CellBorders => ({
+    ...((mask & 1) !== 0 ? { top: border } : {}),
+    ...((mask & 2) !== 0 ? { right: border } : {}),
+    ...((mask & 4) !== 0 ? { bottom: border } : {}),
+    ...((mask & 8) !== 0 ? { left: border } : {}),
+})
+
+/** The sides a base format carries (empty when none). / base 書式の辺集合 (無ければ空)。 */
+const sidesOf = (base: CellFormat | undefined): CellBorders => (base === undefined || base.borders === undefined ? {} : base.borders)
+
+/** The edge bit each single-side preset targets (the `edgeMaskOf` layout). / 単一辺プリセットが対象とする外周辺ビット (`edgeMaskOf` と同配置)。 */
+const SIDE_BITS = { top: 1, right: 2, bottom: 4, left: 8 } as const
+
+/** The default border of the border commands (v0.8 §4.1.13: thin, BORDER_DEFAULT_COLOR). / 罫線コマンドの既定辺 (v0.8 §4.1.13: thin、BORDER_DEFAULT_COLOR)。 */
+const DEFAULT_BORDER: CellBorder = { style: "thin", color: BORDER_DEFAULT_COLOR }
+
+/** Structural colour equality through normalizeColor (unparseable never equals). / normalizeColor を通した色の等価 (解釈不能は決して等しくない)。 */
+const sameColor = (a: string | undefined, b: string): boolean => {
+    if (a === undefined) {
+        return false
+    }
+    const na = normalizeColor(a)
+    return na !== null && na === normalizeColor(b)
+}
+
+/**
+ * The value format a `format*` command writes (the host's locale stamped when declared;
+ * `currency` REQUIRES the `formats` prop — the availability gate keeps the row absent without it,
+ * so reaching this branch undeclared is a runner bug, reported as a RangeError rather than a
+ * substituted currency).
+ * format* コマンドが書く値書式 (ホストが locale を宣言していれば刻印。currency は formats prop 必須 —
+ * 可用性ゲートが未宣言時は行不在にするため、未宣言でここへ達するのは実行器のバグであり、通貨の代替
+ * ではなく RangeError で報告)。
+ */
+const valueFormatOf = (value: ValueKind, formats: CommandFormats | undefined): CellValueFormat => {
+    // locale は宣言時だけ刻印 (undefined キーを書かない)
+    const locale = formats === undefined || formats.locale === undefined ? {} : { locale: formats.locale }
+    switch (value) {
+        case "number":
+            return { type: "number", decimals: 2, grouping: true, ...locale }
+        case "time":
+            return { type: "date", pattern: "HH:mm:ss" }
+        case "date":
+            return { type: "date" }
+        case "currency":
+            if (formats === undefined) {
+                throw new RangeError("[spreadsheet] formatCurrency requires the formats prop (currency)")
+            }
+            return { type: "currency", currency: formats.currency, decimals: 2, ...locale }
+        case "percent":
+            return { type: "percent", decimals: 2, ...locale }
+        default:
+            return { type: "scientific", decimals: 2, ...locale }
+    }
+}
+
+/**
+ * Builds the command runner.
+ * コマンド実行器を構築する。
+ */
+export const useCommands = (params: UseCommandsParams): CommandRunner => {
+    // paramsRef パターン: 戻り値のコールバックは identity 安定、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    /** The write targets: the session cell while editing, else every selected range. / 書込対象: 編集中はセッションセル、それ以外は全選択レンジ。 */
+    const targetRanges = useCallback((): readonly CellRange[] => {
+        const p = paramsRef.current
+        if (p.isEditing()) {
+            const active = p.getActive()
+            return [makeRange(active, active)]
+        }
+        return p.getSelection().ranges
+    }, [])
+
+    /** The active cell's BASE format (capability branch). / active セルの BASE 書式 (能力分岐)。 */
+    const activeBase = useCallback((): CellFormat | undefined => {
+        const p = paramsRef.current
+        const active = p.getActive()
+        return p.adapter.getCellFormat === undefined ? undefined : p.adapter.getCellFormat(active.row, active.col)
+    }, [])
+
+    /**
+     * The format write core: gate → enumerate → mergeFormat memoised per (patch bucket, base
+     * identity) → ONE commit with source "format" → sink repaint while editing. `patchOf` receives
+     * the cell, its range and its base (already read once here — never a second adapter read).
+     * 書式書込の中核: ゲート → 走査 → (パッチ束, base identity) 毎に memo した mergeFormat → source
+     * "format" の commit 1 回 → 編集中はシンク再塗り。patchOf はセル・レンジ・base (ここで 1 回読んだ
+     * もの — アダプタを二度読みしない) を受け取る。
+     */
+    const writeFormat = useCallback(
+        (patchOf: (cell: CellCoord, range: CellRange, base: CellFormat | undefined) => { bucket: number; patch: CellFormatPatch }): boolean => {
+            const p = paramsRef.current
+            const ranges = targetRanges()
+            if (!gateSelectionWrite("format", ranges, p.maxOperationCells, p.onOperationRejected)) {
+                return false
+            }
+            // memo: バケット (パッチの同一性) × base identity — パッチはジェスチャ内で定数なので
+            // intern された base 1 つにつき mergeFormat は 1 回 (applyEdits 引数の format identity は 1 つ)
+            const memo = new Map<number, Map<CellFormat | undefined, CellFormat | undefined>>()
+            const edits: CellEdit[] = []
+            const read = p.adapter.getCellFormat
+            for (const range of ranges) {
+                enumerateRangeCells([range], (cell) => {
+                    const base = read === undefined ? undefined : read(cell.row, cell.col)
+                    const { bucket, patch } = patchOf(cell, range, base)
+                    let byBase = memo.get(bucket)
+                    if (byBase === undefined) {
+                        byBase = new Map()
+                        memo.set(bucket, byBase)
+                    }
+                    let next: CellFormat | undefined
+                    if (byBase.has(base)) {
+                        next = byBase.get(base)
+                    } else {
+                        next = mergeFormat(base, patch)
+                        byBase.set(base, next)
+                    }
+                    // 無変化 (identity) は edit を出さない
+                    if (next === base) {
+                        return
+                    }
+                    edits.push({ row: cell.row, col: cell.col, format: next === undefined ? null : next })
+                })
+            }
+            if (edits.length === 0) {
+                return true
+            }
+            if (p.commitEdits(edits, { source: "format" }) === null) {
+                return false
+            }
+            // 編集列: セッションセルの書式が変わったのでシンクを再塗り
+            if (p.isEditing()) {
+                p.refreshEditPaint()
+            }
+            return true
+        },
+        [targetRanges],
+    )
+
+    /** A constant patch (computed once) applied to every target. / 定数パッチ (1 回計算) を全対象へ。 */
+    const writeConstantPatch = useCallback((patch: CellFormatPatch): boolean => writeFormat(() => ({ bucket: 0, patch })), [writeFormat])
+
+    /** Pushes the opt-in announcement after a successful format command. / 書式コマンド成功後の opt-in 告知。 */
+    const announceFormat = useCallback((command: SpreadsheetCommand, state: boolean | null): void => {
+        const p = paramsRef.current
+        if (p.formatCommandAnnouncement !== undefined) {
+            p.announce(p.formatCommandAnnouncement({ command, state }))
+        }
+    }, [])
+
+    const setBorders = useCallback(
+        (preset: BorderPreset, border: CellBorder = DEFAULT_BORDER): boolean => {
+            if (preset === "clear") {
+                return writeConstantPatch({ borders: null })
+            }
+            if (preset === "all") {
+                return writeConstantPatch({ borders: { top: border, right: border, bottom: border, left: border } })
+            }
+            // 位置依存 (outer = 全外周辺 / 単一辺 = レンジの当該外周辺だけ — Excel / Sheets のレンジ辺
+            // 意味論、分冊 08 §11): 各セル自身の辺を展開し該当辺だけを置く (borders は集合置換 — 内側 /
+            // 辺外のセルは辺を保つ)。memo は辺マスク毎で、マスク 0 は identity merge となり edit なし
+            const presetMask = preset === "outer" ? 15 : SIDE_BITS[preset]
+            return writeFormat((cell, range, base) => {
+                const mask = edgeMaskOf(cell, range) & presetMask
+                return { bucket: mask, patch: { borders: { ...sidesOf(base), ...sidesOfMask(mask, border) } } }
+            })
+        },
+        [writeConstantPatch, writeFormat],
+    )
+
+    /** Copies one source cell (text / shifted formula + declared aspects, comments excluded) onto targets — the fill handle's per-source rule (`readFillSource` / `fillSourceEdit`). / ソースセル 1 個 (text / シフト数式 + 宣言済み側面、comments 除外) を対象へ複製 — fill ハンドルと同じソース毎規則 (`readFillSource` / `fillSourceEdit`)。 */
+    const fillEdits = useCallback((source: CellCoord, targets: readonly CellCoord[], edits: CellEdit[]): void => {
+        // ソースは 1 回だけ解決し、対象毎に数式シフト + 側面キーの複製 (ハンドルドラッグと同一規則)
+        const resolved = readFillSource(paramsRef.current.adapter, source.row, source.col)
+        for (const target of targets) {
+            edits.push(fillSourceEdit(resolved, source, target))
+        }
+    }, [])
+
+    /** fillDown / fillRight / fillSelection (idle). / fillDown / fillRight / fillSelection (idle)。 */
+    const runFill = useCallback(
+        (direction: "down" | "right" | "selection"): boolean => {
+            const p = paramsRef.current
+            const selection = p.getSelection()
+            if (!gateSelectionWrite("fill", selection.ranges, p.maxOperationCells, p.onOperationRejected)) {
+                return false
+            }
+            const edits: CellEdit[] = []
+            if (direction === "selection") {
+                // active の内容を active 以外の全選択セルへ
+                const active = selection.active
+                const targets: CellCoord[] = []
+                enumerateRangeCells(selection.ranges, (cell) => {
+                    if (cell.row !== active.row || cell.col !== active.col) {
+                        targets.push(cell)
+                    }
+                })
+                fillEdits(active, targets, edits)
+            } else {
+                for (const range of selection.ranges) {
+                    if (direction === "down") {
+                        const single = range.startRow === range.endRow
+                        // 1 行のレンジは上隣を複製 (行 0 は上隣が無い — 何もしない)
+                        if (single && range.startRow === 0) {
+                            continue
+                        }
+                        const sourceRow = single ? range.startRow - 1 : range.startRow
+                        for (let col = range.startCol; col <= range.endCol; col += 1) {
+                            const targets: CellCoord[] = []
+                            for (let row = single ? range.startRow : range.startRow + 1; row <= range.endRow; row += 1) {
+                                targets.push({ row, col })
+                            }
+                            fillEdits({ row: sourceRow, col }, targets, edits)
+                        }
+                    } else {
+                        const single = range.startCol === range.endCol
+                        // 1 列のレンジは左隣を複製 (列 0 は左隣が無い — 何もしない)
+                        if (single && range.startCol === 0) {
+                            continue
+                        }
+                        const sourceCol = single ? range.startCol - 1 : range.startCol
+                        for (let row = range.startRow; row <= range.endRow; row += 1) {
+                            const targets: CellCoord[] = []
+                            for (let col = single ? range.startCol : range.startCol + 1; col <= range.endCol; col += 1) {
+                                targets.push({ row, col })
+                            }
+                            fillEdits({ row, col: sourceCol }, targets, edits)
+                        }
+                    }
+                }
+            }
+            if (edits.length === 0) {
+                return true
+            }
+            return p.commitEdits(edits, { source: "fill" }) !== null
+        },
+        [fillEdits],
+    )
+
+    /** Self-calc over the selection (source "calc"). / 選択の自己計算 (source "calc")。 */
+    const runCalc = useCallback((transform: { text: (text: string) => string | null; formula: (formula: string) => string }): boolean => {
+        const p = paramsRef.current
+        const selection = p.getSelection()
+        if (!gateSelectionWrite("calc", selection.ranges, p.maxOperationCells, p.onOperationRejected)) {
+            return false
+        }
+        const edits: CellEdit[] = []
+        const adapter = p.adapter
+        enumerateRangeCells(selection.ranges, (cell) => {
+            // 数式扱いは getCellFormula 宣言時のみ (text 側は "=" を嗅がない)
+            const formula = adapter.getCellFormula === undefined ? undefined : adapter.getCellFormula(cell.row, cell.col)
+            const next = formula === undefined ? transform.text(adapter.getCellText(cell.row, cell.col)) : transform.formula(formula)
+            // null = 変換不能 (非数 / 非真偽値) — そのセルは触らない
+            if (next !== null) {
+                edits.push({ row: cell.row, col: cell.col, text: next })
+            }
+        })
+        if (edits.length === 0) {
+            return true
+        }
+        return p.commitEdits(edits, { source: "calc" }) !== null
+    }, [])
+
+    /** hideRows / hideColumns / unhideRows / unhideColumns through the resize gates. / hide / unhide (リサイズゲート経由)。 */
+    const runHide = useCallback((axisKind: "row" | "col", hide: boolean): boolean => {
+        const p = paramsRef.current
+        const axis = axisKind === "row" ? p.rowAxis : p.colAxis
+        const selection = p.getSelection()
+        // 実体化前の保守カウント (レンジ跨ぎの重複は重複のまま数える — useHeaderResize の collectTargets と同じ規律)
+        const limit = axisKind === "row" ? Math.floor(p.maxOperationCells / ROW_FANOUT_DIVISOR) : p.maxOperationCells
+        let span = 0
+        for (const range of selection.ranges) {
+            span += axisKind === "row" ? range.endRow - range.startRow + 1 : range.endCol - range.startCol + 1
+        }
+        if (span > limit) {
+            p.onOperationRejected?.("resize", span, "limit")
+            return false
+        }
+        const seen = new Set<number>()
+        const entries: ResizeEntry[] = []
+        const size = hide ? 0 : axisKind === "row" ? p.defaultRowHeight : p.defaultColumnWidth
+        for (const range of selection.ranges) {
+            const start = axisKind === "row" ? range.startRow : range.startCol
+            const end = axisKind === "row" ? range.endRow : range.endCol
+            for (let index = start; index <= end; index += 1) {
+                if (seen.has(index)) {
+                    continue
+                }
+                seen.add(index)
+                // hide は可視トラックだけ、unhide は非表示トラックだけを対象にする
+                const hidden = axis.sizeOf(index) === 0
+                if (hidden !== hide) {
+                    entries.push({ index, size })
+                }
+            }
+        }
+        const result = gateResizeEntries(axis, entries, null, { maxOperationCells: p.maxOperationCells, rowHiddenLimit: ROW_HIDDEN_LIMIT, axisKind })
+        if (!result.ok) {
+            p.onOperationRejected?.("resize", result.count, result.reason)
+            return false
+        }
+        // 対象トラックが無ければ幾何に触れない
+        if (result.entries.length > 0) {
+            p.resizeTracks(axisKind, result.entries)
+        }
+        return true
+    }, [])
+
+    /** The active cell's hyperlink through the declared aspect (undefined = no link, the aspect is undeclared, or the raw URL fails the allowlist — the read trust boundary, ADR-10). / 宣言済み側面経由の active セルのリンク (undefined = リンク無し、側面未宣言、または生 URL が許可リスト外 — 読み口の信頼境界、ADR-10)。 */
+    const activeHyperlink = useCallback((): string | undefined => {
+        const p = paramsRef.current
+        // 側面未宣言はリンク無しと同じ (能力分岐)
+        if (p.adapter.getCellHyperlink === undefined) {
+            return undefined
+        }
+        const active = p.getActive()
+        // 信頼境界: 許可外スキームはリンク無し — 開通ゲートにも onHyperlinkOpen にも生 URL を渡さない
+        return normalizeAdapterHyperlink(p.adapter.getCellHyperlink(active.row, active.col))
+    }, [])
+
+    /** The capability gate (the keymap row exists only when true — `openHyperlink` with a declared host is cell-aware). / 能力ゲート (true のときだけキーマップ行が存在 — host 宣言時の `openHyperlink` はセル依存)。 */
+    const isCommandAvailable = useCallback(
+        (command: SpreadsheetCommand): boolean => {
+            const p = paramsRef.current
+            const adapter = p.adapter
+            const spec = COMMAND_SPECS[command]
+            const formatDeclared = adapter.getCellFormat !== undefined
+            const popoverEnabled = (kind: PopoverKind): boolean => (p.popovers === undefined ? true : p.popovers[kind] !== false)
+            switch (spec.kind) {
+                case "toggle":
+                case "patch":
+                case "clear":
+                case "borders":
+                case "color":
+                    return formatDeclared
+                case "value":
+                    return formatDeclared && (spec.value !== "currency" || p.formats !== undefined)
+                case "popover":
+                    switch (spec.popover) {
+                        case "link":
+                            return adapter.getCellHyperlink !== undefined && popoverEnabled("link")
+                        case "note":
+                            return adapter.getCellNote !== undefined && popoverEnabled("note")
+                        case "comment":
+                            return adapter.getCellComments !== undefined && popoverEnabled("comment")
+                        default:
+                            return adapter.getCellValidation !== undefined && popoverEnabled("list")
+                    }
+                case "openHyperlink":
+                    // host 宣言時: active にリンクがあるときだけ行が存在 (リンク無しは素通し — README / 分冊 04 §3.2 / 08 §6.3)。
+                    // 未宣言: link ポップオーバーが開ける限り行あり (Ctrl+K 同等 — リンク無しでも編集器を開く)
+                    return adapter.getCellHyperlink !== undefined && (p.onHyperlinkOpen !== undefined ? activeHyperlink() !== undefined : popoverEnabled("link"))
+                case "paste":
+                    return spec.options.mode === "formats" ? formatDeclared : spec.options.mode === "formulas" ? adapter.getCellFormula !== undefined : true
+                default:
+                    return true
+            }
+        },
+        [activeHyperlink],
+    )
+
+    const executeCommand = useCallback(
+        (command: SpreadsheetCommand): boolean => {
+            const p = paramsRef.current
+            if (!isCommandAvailable(command)) {
+                return false
+            }
+            const spec = COMMAND_SPECS[command]
+            const editing = p.isEditing()
+            // 編集列に無いコマンドは先にセッションを確定する (拒否なら中断)
+            if (editing && !EDITING_COLUMN_COMMANDS.has(command) && !p.requestCommit()) {
+                return false
+            }
+            switch (spec.kind) {
+                case "toggle": {
+                    const base = activeBase()
+                    // active の BASE から 1 回だけ: on なら消去 (null)、off なら true — 混在選択は active に従う
+                    const on = base !== undefined && base[spec.key] === true
+                    if (!writeConstantPatch({ [spec.key]: on ? null : true })) {
+                        return false
+                    }
+                    announceFormat(command, !on)
+                    return true
+                }
+                case "patch": {
+                    if (!writeConstantPatch(spec.patch)) {
+                        return false
+                    }
+                    announceFormat(command, null)
+                    return true
+                }
+                case "clear": {
+                    if (!writeConstantPatch(CLEAR_PATCH)) {
+                        return false
+                    }
+                    announceFormat(command, null)
+                    return true
+                }
+                case "value": {
+                    if (!writeConstantPatch({ value: valueFormatOf(spec.value, p.formats) })) {
+                        return false
+                    }
+                    announceFormat(command, null)
+                    return true
+                }
+                case "borders": {
+                    if (!setBorders(spec.preset)) {
+                        return false
+                    }
+                    announceFormat(command, null)
+                    return true
+                }
+                case "color": {
+                    // 目標色: プリセットか colors スロット (スロット不在は行不在と同じ = 何もしない)
+                    const slots = spec.key === "background" ? p.colors.fill : p.colors.font
+                    const target = spec.preset !== null ? spec.preset : spec.custom !== null && spec.custom < slots.length ? slots[spec.custom] : undefined
+                    if (target === undefined) {
+                        return false
+                    }
+                    const base = activeBase()
+                    // active の BASE 色が目標と等しければ選択全体を消去、違えば目標へ
+                    const on = sameColor(base === undefined ? undefined : base[spec.key], target)
+                    if (!writeConstantPatch({ [spec.key]: on ? null : target })) {
+                        return false
+                    }
+                    announceFormat(command, !on)
+                    return true
+                }
+                case "calc":
+                    return runCalc({ text: (text) => scaleDecimalText(text, spec.exponent), formula: (formula) => scaleFormula(formula, spec.exponent) })
+                case "sign":
+                    return runCalc({ text: reverseSignText, formula: reverseSignFormula })
+                case "fill": {
+                    if (editing && spec.direction === "selection") {
+                        // 編集列: セッション文字列を全選択セルへ 1 applyEdits、セッション閉鎖
+                        const text = p.getSessionText()
+                        if (text === null) {
+                            return false
+                        }
+                        const selection = p.getSelection()
+                        if (!gateSelectionWrite("fill", selection.ranges, p.maxOperationCells, p.onOperationRejected)) {
+                            return false
+                        }
+                        // 検証ゲート (分冊 08 §4.2) は対象セル毎 — 規則はセル毎に違い得る。最初の strict 拒否で
+                        // 走査を打ち切り applyEdits へ届けない (通知と message ポップオーバーは root の validateCommit が担う)
+                        const edits: CellEdit[] = []
+                        let rejected = false
+                        enumerateRangeCells(selection.ranges, (cell) => {
+                            if (rejected) {
+                                return
+                            }
+                            if (!p.validateCommit(cell, text).ok) {
+                                rejected = true
+                                return
+                            }
+                            edits.push({ row: cell.row, col: cell.col, text })
+                        })
+                        // 拒否はセッション維持のまま false (Enter の keep 経路と同じ — Escape で取消 / 修正して再試行)
+                        if (rejected) {
+                            return false
+                        }
+                        if (p.commitEdits(edits, { source: "fill" }) === null) {
+                            return false
+                        }
+                        // 値は全セルへ書かれた — セッションは破棄で閉じる (二重書込なし)
+                        p.cancelEdit()
+                        return true
+                    }
+                    return runFill(spec.direction)
+                }
+                case "popover":
+                    p.openPopover(spec.popover)
+                    return true
+                case "openHyperlink": {
+                    if (p.onHyperlinkOpen !== undefined) {
+                        const url = activeHyperlink()
+                        // リンク無しは isCommandAvailable が先に落とす (行不在 = 素通し) — ここは型の絞り込みだけ
+                        if (url === undefined) {
+                            return false
+                        }
+                        p.onHyperlinkOpen(url, p.getActive())
+                        return true
+                    }
+                    // 未宣言: link ポップオーバー (Open ボタンなし)
+                    p.openPopover("link")
+                    return true
+                }
+                case "pasteSpecial": {
+                    if (p.onPasteSpecialRequest !== undefined) {
+                        p.onPasteSpecialRequest({ kind: "keyboard", cellRect: p.keyboardCellRect() })
+                        return true
+                    }
+                    // 未宣言: 書式のみ貼り付け (メニュー経路)
+                    void p.paste({ mode: "formats" })
+                    return true
+                }
+                case "paste":
+                    void p.paste(spec.options)
+                    return true
+                case "insertNow": {
+                    const text = spec.unit === "date" ? formatLocalDate(p.now()) : formatLocalTime(p.now())
+                    if (editing) {
+                        p.insertAtCaret(text)
+                        return true
+                    }
+                    // idle: active セルだけへ 1 applyEdits (選択全体には書かない)、直接確定 (セッションは無い = discarded)
+                    const active = p.getActive()
+                    // Excel の Ctrl+; は編集モード経由で Enter 確定が検証される (strict ⇒ 拒否) — 分冊 08 §4.2 の
+                    // fill / 貼り付け非検証免除はここへ及ばないため、strict 拒否は書込前に判定する
+                    // (通知と message ポップオーバーは root の validateCommit が担う)
+                    if (!p.validateCommit(active, text).ok) {
+                        return false
+                    }
+                    return p.commitEdits([{ row: active.row, col: active.col, text }], { source: "edit", editSession: "discarded" }) !== null
+                }
+                case "hide":
+                    return runHide(spec.axis, spec.hide)
+                default: {
+                    const h = p.getHighlight()
+                    switch (spec.target) {
+                        case "row":
+                            p.setHighlight({ ...h, row: !h.row })
+                            return true
+                        case "column":
+                            p.setHighlight({ ...h, column: !h.column })
+                            return true
+                        case "both": {
+                            // 両方 on のときだけ off へ、それ以外は両方 on へ
+                            const on = h.row && h.column
+                            p.setHighlight({ ...h, row: !on, column: !on })
+                            return true
+                        }
+                        default:
+                            p.setHighlight({ ...h, intersection: !h.intersection })
+                            return true
+                    }
+                }
+            }
+        },
+        [isCommandAvailable, activeHyperlink, activeBase, writeConstantPatch, announceFormat, setBorders, runCalc, runFill, runHide],
+    )
+
+    /** Commit gate shared by the annotation setters. / 注釈 setter 共通の commit ゲート。 */
+    const commitGate = useCallback((): boolean => {
+        const p = paramsRef.current
+        return !(p.isEditing() && !p.requestCommit())
+    }, [])
+
+    const setHyperlink = useCallback(
+        (url: string | null): boolean => {
+            const p = paramsRef.current
+            if (p.adapter.getCellHyperlink === undefined) {
+                throw new RangeError("[spreadsheet] setHyperlink requires the getCellHyperlink capability")
+            }
+            const normalized = url === null ? null : normalizeHyperlink(url)
+            if (url !== null && normalized === null) {
+                throw new RangeError(`[spreadsheet] setHyperlink received an unnormalisable url ${JSON.stringify(url)}`)
+            }
+            if (!commitGate()) {
+                return false
+            }
+            const active = p.getActive()
+            return p.commitEdits([{ row: active.row, col: active.col, hyperlink: normalized }], { source: "annotate" }) !== null
+        },
+        [commitGate],
+    )
+
+    const setNote = useCallback(
+        (text: string | null): boolean => {
+            const p = paramsRef.current
+            if (p.adapter.getCellNote === undefined) {
+                throw new RangeError("[spreadsheet] setNote requires the getCellNote capability")
+            }
+            if (!commitGate()) {
+                return false
+            }
+            const active = p.getActive()
+            return p.commitEdits([{ row: active.row, col: active.col, note: text }], { source: "annotate" }) !== null
+        },
+        [commitGate],
+    )
+
+    const addComment = useCallback(
+        (input: CellCommentInput): boolean => {
+            const p = paramsRef.current
+            const read = p.adapter.getCellComments
+            if (read === undefined) {
+                throw new RangeError("[spreadsheet] addComment requires the getCellComments capability")
+            }
+            if (!commitGate()) {
+                return false
+            }
+            const active = p.getActive()
+            // 既存スレッド (id つき) を verbatim に保ち input を末尾へ — 1 スレッドとして書く
+            const existing = read(active.row, active.col)
+            const thread: CellCommentInput[] = existing === undefined ? [input] : [...existing, input]
+            return p.commitEdits([{ row: active.row, col: active.col, comments: thread }], { source: "annotate" }) !== null
+        },
+        [commitGate],
+    )
+
+    const setValidation = useCallback(
+        (rule: DataValidationRule | null): boolean => {
+            const p = paramsRef.current
+            if (p.adapter.getCellValidation === undefined) {
+                throw new RangeError("[spreadsheet] setValidation requires the getCellValidation capability")
+            }
+            if (!commitGate()) {
+                return false
+            }
+            const ranges = p.getSelection().ranges
+            if (!gateSelectionWrite("annotate", ranges, p.maxOperationCells, p.onOperationRejected)) {
+                return false
+            }
+            const edits: CellEdit[] = []
+            enumerateRangeCells(ranges, (cell) => {
+                edits.push({ row: cell.row, col: cell.col, validation: rule })
+            })
+            return p.commitEdits(edits, { source: "annotate" }) !== null
+        },
+        [commitGate],
+    )
+
+    const applyFormat = useCallback(
+        (patch: CellFormatPatch): boolean => {
+            if (paramsRef.current.adapter.getCellFormat === undefined) {
+                throw new RangeError("[spreadsheet] applyFormat requires the getCellFormat capability")
+            }
+            return writeConstantPatch(patch)
+        },
+        [writeConstantPatch],
+    )
+
+    const setBordersPublic = useCallback(
+        (preset: BorderPreset, border?: CellBorder): boolean => {
+            if (paramsRef.current.adapter.getCellFormat === undefined) {
+                throw new RangeError("[spreadsheet] setBorders requires the getCellFormat capability")
+            }
+            return setBorders(preset, border)
+        },
+        [setBorders],
+    )
+
+    return useMemo(() => ({ executeCommand, applyFormat, setBorders: setBordersPublic, setHyperlink, setNote, addComment, setValidation, isCommandAvailable }), [executeCommand, applyFormat, setBordersPublic, setHyperlink, setNote, addComment, setValidation, isCommandAvailable])
+}