@aiquants/spreadsheet 0.8.0

package/src/model/dataAdapter.ts

@@ -0,0 +1,478 @@
+/**
+ * @fileoverview The single data boundary between the grid and the consumer (v0.8 — ADR-13
+ * rich cells / ADR-16 write vocabulary): the adapter type with its eight optional rich-cell
+ * capability reads, the per-cell PATCH the grid writes (CellPatch / CellEdit — an absent key is
+ * untouched, `null` clears), the discriminated write context every applyEdits receives
+ * (EditContext — one transaction id per gesture; the paste arm carries `sameSheet` and the
+ * pasted conditional-format inputs), the write-rejection context (EditRejection — what
+ * onEditRejected reports when applyEdits throws) and the four adapter-level pure helpers every
+ * consumer of the boundary shares: resolveCellAlign (the ONE alignment judgment, over the
+ * PAINTED format = base ⊕ conditional formats), lazyCellText (the once-only text thunk = the
+ * eighth read of a cell), resolveEditText (the editor seed — formula source or canonical text,
+ * fail-fast on a formula that does not start with "=") and aspectCapabilities (the write gate's
+ * single reader of the declared aspects). Every capability is a DECLARATION: absence is a code
+ * branch that reproduces the v0.7 behaviour exactly, never a value fallback.
+ * グリッドと consumer の唯一のデータ境界 (v0.8 — ADR-13 リッチセル / ADR-16 書込語彙): 8 つの
+ * 任意リッチセル能力読みを持つアダプタ型、グリッドが書くセル単位パッチ (CellPatch / CellEdit —
+ * 未指定キーは「触らない」、`null` は「消す」)、全 applyEdits が受け取る判別可能な書込文脈
+ * (EditContext — ジェスチャ毎に 1 トランザクション id、paste 枝は `sameSheet` と貼り付けた条件付き
+ * 書式入力を運ぶ)、書込拒否文脈 (EditRejection — applyEdits の throw を onEditRejected が報告する
+ * 形)、境界の全消費者が共有するアダプタ水準の純関数 4 つ: resolveCellAlign (唯一の揃え判定 —
+ * **塗り書式** = base ⊕ 条件付き書式に対して)、lazyCellText (遅延 1 回読みの text thunk = セル
+ * 8 読み目)、resolveEditText (エディタ初期文字列 — 数式ソースか正準文字列、"=" 非始まりの数式は
+ * fail-fast)、aspectCapabilities (書込ゲートの宣言済み側面の単一読み)。全能力は**宣言**であり、
+ * 未宣言は v0.7 の振る舞いを厳密に再現するコード分岐 — 値フォールバックではない。
+ */
+
+import type { CellComment, CellCommentInput } from "./cellAnnotations.ts"
+import type { CellCoord, CellRange, SpreadsheetDirection } from "./cellCoord.ts"
+import { type CellAlign, type CellFormat, resolveAlign } from "./cellFormat.ts"
+import type { ConditionalFormatRule, ConditionalFormatRuleInput } from "./conditionalFormat.ts"
+import type { DataValidationRule } from "./dataValidation.ts"
+
+/**
+ * One per-cell PATCH (ADR-16): an ABSENT key leaves that aspect untouched, `null` CLEARS it, a
+ * value replaces it whole. `text` is the canonical string (a cleared cell is `text: ""` — text
+ * has no `null`); `format` is the complete CANONICAL CellFormat of the cell after the gesture
+ * (the command runner merges its patch with the base format BEFORE the adapter sees it — a
+ * CellFormatPatch never crosses this boundary; `null` removes every format key); `note` is the
+ * note text; `comments` carries the WHOLE thread: an input WITH `id` is an existing comment the
+ * consumer keeps verbatim, an input WITHOUT `id` is a new comment the consumer stamps with
+ * id / author / createdAt (the package never mints an id; `author` / `createdAt` travel only when a
+ * paste replays a foreign thread), `null` clears the thread; `hyperlink` is the normalized URL
+ * (normalizeHyperlink — one of http / https / mailto / tel); `validation` is the rule object.
+ * セル 1 件のパッチ (ADR-16): **未指定**キーはその側面を触らず、`null` は消去、値は丸ごと置換。
+ * `text` は正準文字列 (消去は `text: ""` — text に `null` は無い)。`format` はジェスチャ後のセルの
+ * **完全な正準** CellFormat (コマンド実行器はアダプタに渡す前に base 書式とパッチを合成する —
+ * CellFormatPatch はこの境界を跨がない。`null` は全書式キーの除去)。`note` はノート本文。
+ * `comments` は**スレッド全体**: `id` つき入力は consumer が verbatim に保持する既存コメント、`id`
+ * なし入力は consumer が id / author / createdAt を刻印する新規コメント (パッケージは採番しない。
+ * `author` / `createdAt` は paste が外部スレッドを再生するときだけ運ぶ)、`null` はスレッド消去。
+ * `hyperlink` は正規化済み URL (normalizeHyperlink — http / https / mailto / tel のいずれか)、
+ * `validation` は規則 object。
+ */
+export type CellPatch = { text?: string; format?: CellFormat | null; note?: string | null; comments?: readonly CellCommentInput[] | null; hyperlink?: string | null; validation?: DataValidationRule | null }
+
+/**
+ * One cell write: a coordinate plus a {@link CellPatch}. A v0.7 text edit `{ row, col, text }`
+ * is still a CellEdit; a format-only edit omits `text` entirely.
+ * セル書込 1 件: 座標 + {@link CellPatch}。v0.7 のテキスト編集 `{ row, col, text }` もそのまま
+ * CellEdit であり、書式だけの編集は `text` を持たない。
+ */
+export type CellEdit = { row: number; col: number } & CellPatch
+
+/**
+ * Every write path of the grid (the union of the two EditContext arms' `source`; equal to
+ * `EditRejection["source"]`, sealed in dataAdapter.spec.ts): the editor commit ("edit" — also
+ * the idle insertDate / insertTime write), the ADR-12 write gestures ("paste" / "fill" /
+ * "delete") and the v0.8 command families ("format" = format commands / handle writes, "calc"
+ * = multiply / divide / sign-reversal self-calculation, "annotate" = note / comment / hyperlink /
+ * validation writes). A cut-move is the Ctrl+V gesture and is "paste" (Ctrl+X only serializes).
+ * グリッドの全書込経路 (EditContext 2 枝の `source` の和 = `EditRejection["source"]`、
+ * dataAdapter.spec.ts が封印): エディタ確定 ("edit" — 待機中の insertDate / insertTime 書込も)、
+ * ADR-12 の書込ジェスチャ ("paste" / "fill" / "delete")、v0.8 のコマンド族 ("format" = 書式
+ * コマンド / handle 書込、"calc" = 乗除 / 符号反転の自己計算、"annotate" = ノート / コメント /
+ * リンク / 検証の書込)。cut-move は Ctrl+V のジェスチャで "paste" (Ctrl+X は直列化のみ)。
+ */
+export type EditSource = "edit" | "paste" | "fill" | "delete" | "format" | "calc" | "annotate"
+
+/**
+ * Write context of every non-paste applyEdits: `transaction` is the id the grid allocated for
+ * this gesture (strictly increasing per grid instance, one id per applyEdits call — the
+ * consumer's undo groups by it) and `source` names the write path. Spelled as an explicit
+ * literal union (api-extractor cannot roll up `Exclude<EditSource, "paste">`); its agreement
+ * with EditSource is sealed by the type-parity guard in dataAdapter.spec.ts.
+ * paste 以外の全 applyEdits の書込文脈: `transaction` はグリッドがこのジェスチャに採番した id
+ * (グリッド実体毎に厳密増加、applyEdits 呼び出し 1 回につき 1 id — consumer の Undo はこれで
+ * 束ねる)、`source` は書込経路。明示リテラル union で綴る (api-extractor は
+ * `Exclude<EditSource, "paste">` を d.ts ロールアップできない)。EditSource との一致は
+ * dataAdapter.spec.ts の型パリティガードが封印する。
+ */
+export type PlainEditContext = { transaction: number; source: "edit" | "fill" | "delete" | "format" | "calc" | "annotate" }
+
+/**
+ * Write context of a paste (incl. a cut-move, which is the Ctrl+V gesture): `sameSheet` is
+ * true when the clip was copied from THIS adapter and false for a cross-sheet paste — and for
+ * the source-side clear of a cross-sheet cut, which the grid delivers to the SOURCE adapter with
+ * the same transaction id and `conditionalFormats: []` (a cut never moves or removes conditional
+ * formats from the source sheet — deviation row). `conditionalFormats` are the rules pasted with
+ * the cells, translated to the target ranges (`[]` when none; a CF-only paste has `edits: []`
+ * and a non-empty list); the consumer mints each new rule's id — `sourceRuleId` is the id on the
+ * source sheet.
+ * 貼り付け (Ctrl+V のジェスチャである cut-move を含む) の書込文脈: `sameSheet` はクリップが
+ * **この**アダプタからコピーされたとき true、跨ぎ貼り付けは false — 跨ぎ cut の元シート側の消去
+ * も false で、グリッドは**元**アダプタへ同じ transaction id と `conditionalFormats: []` で届ける
+ * (cut は元シートの条件付き書式を移動も削除もしない — 逸脱行)。`conditionalFormats` はセルと共に
+ * 貼り付けた規則を対象レンジへ平行移動したもの (規則なしは `[]`。CF だけの貼り付けは `edits: []`
+ * + 非空リスト)。新規則の id は consumer が採番 — `sourceRuleId` は元シートでの id。
+ */
+export type PasteEditContext = { transaction: number; source: "paste"; sameSheet: boolean; conditionalFormats: readonly ConditionalFormatRuleInput[] }
+
+/**
+ * The write context of applyEdits — a discriminated union on `source`: exactly the paste arm
+ * carries `sameSheet` / `conditionalFormats`. An EMPTY transaction (no edits and no conditional
+ * formats) never reaches the adapter.
+ * applyEdits の書込文脈 — `source` で判別する union: paste 枝だけが `sameSheet` /
+ * `conditionalFormats` を持つ。**空**トランザクション (edits も条件付き書式も無し) はアダプタへ
+ * 届かない。
+ */
+export type EditContext = PlainEditContext | PasteEditContext
+
+/** Compile-time seal: the plain arm never carries "paste" (the discriminant stays unambiguous, so `context.source === "paste"` narrows to the paste arm alone). / コンパイル時封印: plain 枝は "paste" を持たない (判別子が曖昧にならず `context.source === "paste"` は paste 枝だけに絞れる)。 */
+const plainContextNeverPaste: [Extract<PlainEditContext["source"], "paste">] extends [never] ? true : never = true
+void plainContextNeverPaste
+
+/**
+ * Context of a rejected applyEdits (delivered with the thrown error by onEditRejected). The
+ * write path that was refused — the editor commit ("edit") or one of the SpreadsheetOperation
+ * WRITE vocabulary ("paste" / "fill" / "delete" / "format" / "calc" / "annotate", the same
+ * names onOperationRejected uses for the same gestures: a cut-move is the Ctrl+V gesture and is
+ * "paste" in both callbacks, because Ctrl+X only serializes — "cut" and "copy" never write,
+ * "resize" is geometry) — and, for an in-cell editing commit, the FATE of the session, so a
+ * consumer can tell the user the truth: "kept" (an in-grid commit: Enter / Tab / click — the
+ * session stays open with the typed value and focus, Escape cancels it, or the value can be
+ * fixed) versus "discarded" (a grid-exit focusout: the grid discards the session as this
+ * rejection completes — once the callback returns the typed value is dropped and the sink
+ * re-armed WITHOUT moving focus: it stays on the element the user chose, or on the hidden input
+ * after a window blur (alt-tab — a null relatedTarget takes the same path) — advising "press
+ * Escape" here would be wrong, and an idle Escape would hand focus out of the grid per WCAG
+ * 2.1.2). Non-editing writes carry no session. A discriminated union: impossible combinations
+ * do not type-check.
+ * applyEdits 拒否の文脈 (onEditRejected が throw されたエラーと共に届ける)。拒否された書込経路
+ * (エディタ確定の "edit"、または onOperationRejected が同じジェスチャに使うのと同じ
+ * SpreadsheetOperation の**書込**語彙 "paste" / "fill" / "delete" / "format" / "calc" /
+ * "annotate" — cut-move は Ctrl+V のジェスチャで両コールバックとも "paste"。Ctrl+X は直列化のみで
+ * "cut" と "copy" は書かず、"resize" は幾何) と、セル内編集の確定なら**セッションの行方** —
+ * "kept" (グリッド内確定: Enter / Tab / クリック — 入力値とフォーカスごとセッション維持、Escape で
+ * 取消か修正可能) と "discarded" (グリッド外 focusout: この拒否の完了と同時にグリッドが
+ * セッションを破棄する — コールバックが返った時点で入力値は消え、シンクはフォーカスを動かさずに
+ * 再武装される: フォーカスはユーザーが選んだ要素、またはウィンドウ blur (alt-tab — relatedTarget
+ * null も同じ経路) なら隠し入力のまま。ここで「Escape を押せ」と案内するのは誤りで、待機中の
+ * Escape は WCAG 2.1.2 のフォーカス脱出になる) を消費者が区別できる。非編集の書込はセッションを
+ * 持たない。判別可能 union — あり得ない組合せは型が拒む。
+ */
+// 明示リテラル union で宣言する (api-extractor は Extract<SpreadsheetOperation, ...> 等の lib 汎用型を
+// d.ts ロールアップできず build が落ちる — ScrollToCellOptions と同じ制約)。非 edit の source 集合が
+// SpreadsheetOperation の書込部分集合 (copy / cut / resize を除く) および EditSource と**集合として
+// 一致**することは dataAdapter.spec.ts の型パリティガードが tsc で機械封印する (欠落・外来・非書込の
+// 混入いずれも即赤)
+export type EditRejection = { source: "edit"; editSession: "kept" | "discarded" } | { source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate" }
+
+/**
+ * The single data boundary between the grid and the consumer. Reads via getCellText (renderCell
+ * — a SpreadsheetProps prop, not an adapter member — customizes only the presentation of that
+ * text) plus the optional capability reads, writes via applyEdits as ONE transaction per
+ * gesture (editor commit / Delete / paste / cut-clear / fill / format / calc / annotate). This
+ * seam is where the consumer implements undo (inverse patches grouped by `transaction`). Every
+ * optional member is a CAPABILITY DECLARATION ("what cannot be read cannot be written"): the
+ * grid enables a feature only when the read it depends on is declared, and an undeclared
+ * capability reproduces the v0.7 behaviour exactly (never a value fallback). Declaring
+ * getConditionalFormats without getCellFormat is a RangeError at mount (a painted format is
+ * base ⊕ CF and there is no base without getCellFormat).
+ * グリッドと consumer の唯一のデータ境界。読みは getCellText (renderCell は SpreadsheetProps の
+ * prop であってアダプタメンバーではない — その文字列の表現のみを差し替える) と任意の能力読み、
+ * 書きは applyEdits のジェスチャ毎 1 トランザクション (編集確定 / Delete / 貼り付け / 切り取り
+ * 清算 / フィル / 書式 / 自己計算 / 注釈)。consumer の Undo 実装点 (`transaction` で束ねる逆
+ * パッチ)。任意メンバーは全て**能力宣言** (「読めないものは書けない」): グリッドは依存する読みが
+ * 宣言されたときだけ機能を有効化し、未宣言能力は v0.7 の振る舞いを厳密に再現する (値フォール
+ * バックではない)。getCellFormat なしの getConditionalFormats 宣言はマウント時 RangeError
+ * (塗り書式は base ⊕ CF で、getCellFormat なしに base は無い)。
+ */
+export type SpreadsheetDataAdapter = {
+    rowCount: number
+    colCount: number
+    /** Canonical string used for TSV copy and the editor initial value. / コピーとエディタ初期値の正準文字列。 */
+    getCellText: (row: number, col: number) => string
+    /**
+     * Applies ONE transaction of per-cell patches. String-to-value interpretation is the
+     * consumer's job. Rejection = throw (grid state is preserved and onEditRejected fires with
+     * the {@link EditRejection} context). `context` carries the transaction id and the write path
+     * ({@link EditContext}); a paste additionally says whether the clip came from this adapter and
+     * which conditional formats travel with it. An empty transaction never arrives.
+     * セル単位パッチの 1 トランザクションを適用する。文字列→値の解釈は consumer の責務。拒否は
+     * throw (グリッド状態は保たれ、onEditRejected が {@link EditRejection} 文脈つきで通知される)。
+     * `context` はトランザクション id と書込経路 ({@link EditContext}) を運び、貼り付けはさらに
+     * クリップがこのアダプタ由来かと同伴する条件付き書式を伝える。空トランザクションは届かない。
+     * ❗ 契約: edits は**配列順に適用し、同一セルへの重複はキー単位で後勝ち (last-wins)** — 後の edit が
+     * 持つキーは前の edit の同じキーを上書きし、後の edit が持たないキーは前の edit の値のまま残る。
+     * cut の移動 (clear → 貼り付けの重ね積み) がこの順序意味論に依存する。逆パッチで Undo を実装する
+     * consumer は「最初に現れた edit の適用前値」を inverse として記録すること (参照実装は demo/edit)。
+     */
+    applyEdits: (edits: readonly CellEdit[], context: EditContext) => void
+    /**
+     * OPTIONAL capability: computes the Excel Ctrl+Arrow jump target from `from` in
+     * `direction`. Absence = the grid keeps its v0.1 grid-edge jump (a capability declaration,
+     * NOT a value fallback). The consumer implements Excel semantics (non-empty cell with a
+     * non-empty neighbor: the end of the contiguous non-empty run; otherwise: the next
+     * non-empty cell in the direction; none: the grid edge) because only the store can jump
+     * data-aware in O(occupied) instead of O(cells). The grid validates the return fully
+     * fail-fast BEFORE dispatch (non-integer / out-of-axis / orthogonal drift on the reset
+     * path all throw RangeError, propagated uncaught — reference implementation: demo/edit).
+     * 任意能力: Excel の Ctrl+Arrow ジャンプ先を計算する。未宣言 = v0.1 のグリッド端ジャンプ
+     * 維持 (能力宣言であり値フォールバックではない)。Excel 意味論 (非空 + 隣接非空 → 連続
+     * 非空の末端 / それ以外 → 方向の次の非空セル / 無ければグリッド端) は consumer 責務 —
+     * データを知るストアだけが O(占有セル) で跳べる。戻り値はディスパッチ前に完全 fail-fast
+     * 検証 (非整数 / 軸域外 / reset 経路の直交ドリフトは RangeError を未捕捉で伝播)。
+     */
+    findDataEdge?: (from: CellCoord, direction: SpreadsheetDirection) => CellCoord
+    /**
+     * OPTIONAL capability (v0.7, widened in v0.8): the cell's BASE display format — value
+     * format (undefined = raw text), horizontal alignment (undefined = auto BY THE ACTUAL VALUE:
+     * text that parses under the cell's numeric/date format — or as a strict decimal with no
+     * format — resolves right, labels resolve left), vertical alignment, wrap, colours, font
+     * traits, font family / size and per-side borders. Absence = the v0.1 plain-text,
+     * left-aligned rendering with no format command, no format paste aspect and no handle
+     * format write (a capability declaration, NOT a value fallback). The grid paints the
+     * PAINTED format (this base ⊕ conditional formats); the value format applies to the DISPLAY
+     * string only — editing keeps the raw getCellText (Excel semantics) and copy/TSV carry the raw
+     * value too (a DELIBERATE deviation from Excel, which copies the display — raw preserves the
+     * numeric round-trip). Autofit measures the FORMATTED display, and screen-reader
+     * announcements receive both the raw text and the display string. `renderCell` (a prop)
+     * takes precedence over the built-in VALUE format (raw text flows to the custom renderer),
+     * but the resolved ALIGNMENT and paint are cell properties that still apply under
+     * renderCell. Every format is fail-soft: a non-numeric value in a numeric format, an
+     * invalid date, an out-of-range Intl option or an unparseable colour renders / paints
+     * nothing for that key. Return a shared/interned CellFormat per column (or per cell object)
+     * to avoid per-cell allocation and to keep the paint intern stable; because return values
+     * (like getCellText) are only re-read on a re-slice, publish a live format change by bumping
+     * dataVersion (or swapping the adapter).
+     * 任意能力 (v0.7、v0.8 で拡張): セルの **base** 表示形式 — 値書式 (undefined = 素の文字列)・
+     * 水平揃え (undefined = **実際の値**による自動: 数値 / 日付書式の下で実際に解釈できる文字列と、
+     * 書式なしの厳密 10 進だけ右、ラベルは左)・垂直揃え・折返し・色・字体・フォント族 / サイズ・
+     * 辺毎の罫線。未宣言 = v0.1 の素テキスト左寄せ描画で、書式コマンドも書式の貼り付け側面も
+     * handle の書式書込も無い (能力宣言であり値フォールバックではない)。グリッドが塗るのは
+     * **塗り書式** (この base ⊕ 条件付き書式)。値書式は表示文字列にのみ適用し、編集は素の
+     * getCellText (Excel 意味論)、コピー / TSV も素の値を運ぶ (Excel は表示を写すため**意図的な
+     * 逸脱** — 素値は数値の往復を保つ)。autofit は**整形後の表示**を計測し、読み上げには素の
+     * text と表示文字列の両方を渡す。`renderCell` (prop) は組み込み「値書式」に優先する (素の
+     * text がカスタムレンダラーへ) が、解決済み「揃え」と塗りはセル固有属性として renderCell 下
+     * でも効く。全書式は fail-soft — 数値書式の非数値・無効な日付・範囲外 Intl オプション・解釈
+     * 不能な色はそのキーだけ何も描かない。列毎 (またはセル object 毎) に共有 CellFormat を返すと
+     * セル毎の確保を避け塗りの intern も安定する。戻り値は (getCellText 同様) 再スライス時のみ
+     * 再読込されるため、書式変更の反映は dataVersion 増分 (またはアダプタ差替) で行う。
+     */
+    getCellFormat?: (row: number, col: number) => CellFormat | undefined
+    /**
+     * OPTIONAL capability (v0.8): the cell's formula SOURCE — a string that MUST start with
+     * "=" (anything else is a RangeError raised by resolveEditText before dispatch, the
+     * findDataEdge precedent); undefined = the cell holds a plain value. Declared, the editor
+     * seeds with the formula instead of getCellText, copy serializes formulas as R1C1 so a
+     * paste re-anchors them, the self-calculation commands wrap formula cells, and the
+     * formula-reference pointing gestures (click / Arrow / drag while typing after "=") exist.
+     * Absence = none of that: "=" is ordinary text and Arrow keys commit exactly as v0.7.
+     * 任意能力 (v0.8): セルの数式**ソース** — 必ず "=" で始まる文字列 (それ以外は resolveEditText が
+     * ディスパッチ前に RangeError — findDataEdge の前例)。undefined = 素の値のセル。宣言時、エディタ
+     * は getCellText でなく数式で初期化し、コピーは数式を R1C1 で直列化して貼り付けが再アンカー
+     * し、自己計算コマンドは数式セルをラップし、数式参照ポインティング ("=" 後のクリック / Arrow /
+     * ドラッグ) が存在する。未宣言 = いずれも無し: "=" は普通の文字で、Arrow は v0.7 どおり確定。
+     */
+    getCellFormula?: (row: number, col: number) => string | undefined
+    /**
+     * OPTIONAL capability (v0.8): the cell's note text; undefined = no note. Declared, cells
+     * with a note carry the `data-aqsp-note` marker, the hover note tip and the note popover
+     * (Shift+F2) exist, and the note aspect of copy / paste / fill travels. Absence = no marker,
+     * no popover, the chord passes through, the aspect is stripped before tiling.
+     * 任意能力 (v0.8): セルのノート本文。undefined = ノート無し。宣言時、ノートつきセルは
+     * `data-aqsp-note` マーカーを持ち、ホバーの note tip と note ポップオーバー (Shift+F2) が存在し、
+     * コピー / 貼り付け / フィルの note 側面が運ばれる。未宣言 = マーカーもポップオーバーも無く、
+     * チョードは素通し、側面は tiling 前に除去。
+     */
+    getCellNote?: (row: number, col: number) => string | undefined
+    /**
+     * OPTIONAL capability (v0.8): the cell's comment thread on the READ side — every field
+     * stamped by the consumer (id / author / createdAt / text); undefined or an empty array = no
+     * thread. Declared, threaded cells carry `data-aqsp-comment`, the comment popover
+     * (Ctrl+Alt+M) exists and a reply writes the whole thread back through CellPatch.comments
+     * (existing ids kept, the new input id-less). Absence = no marker / popover, the chord passes
+     * through, the aspect is stripped before tiling (fill never copies comments).
+     * 任意能力 (v0.8): セルのコメントスレッド (**読み側** — id / author / createdAt / text は全て
+     * consumer が刻印済み)。undefined または空配列 = スレッド無し。宣言時、スレッドつきセルは
+     * `data-aqsp-comment` を持ち、コメントポップオーバー (Ctrl+Alt+M) が存在し、返信は
+     * CellPatch.comments でスレッド全体を書き戻す (既存 id 保持、新規入力は id なし)。未宣言 =
+     * マーカー / ポップオーバー無し、チョード素通し、側面は tiling 前に除去 (フィルはコメントを写さない)。
+     */
+    getCellComments?: (row: number, col: number) => readonly CellComment[] | undefined
+    /**
+     * OPTIONAL capability (v0.8): the cell's hyperlink URL; undefined = none. Every read is the
+     * trust boundary (ADR-10): the raw URL goes through `normalizeAdapterHyperlink`, so a URL
+     * outside the allowlist (http / https / mailto / tel) is treated as link-less at every seam —
+     * never navigated, never exported into a clip flavour, never re-committed through
+     * `CellPatch.hyperlink`. Declared, linked cells carry `data-aqsp-link`, Alt+Enter opens the
+     * link (onHyperlinkOpen or the link popover), Ctrl / Meta+click opens it too when
+     * onHyperlinkOpen is declared (spec 08 §11 D-53 — the selection stays frozen), Ctrl+K edits
+     * it, Delete clears the link together with the text (`hyperlink: null`), and the link aspect
+     * of copy / paste / fill travels. Absence = plain cells, the chords pass through, Delete
+     * writes text only.
+     * 任意能力 (v0.8): セルのハイパーリンク URL。undefined = 無し。全読み口が信頼境界 (ADR-10):
+     * 生 URL は `normalizeAdapterHyperlink` を通り、許可リスト外 (http / https / mailto / tel 以外)
+     * の URL は全シームでリンク無し扱い — 航行せず、クリップフレーバーへ書き出さず、
+     * `CellPatch.hyperlink` へ再確定しない。宣言時、リンクつきセルは `data-aqsp-link` を持ち、
+     * Alt+Enter がリンクを開き (onHyperlinkOpen または link ポップオーバー)、onHyperlinkOpen 宣言時は
+     * Ctrl / Meta+クリックでも開き (分冊 08 §11 D-53 — 選択は凍結)、Ctrl+K が編集し、Delete は
+     * テキストと共にリンクを消し (`hyperlink: null`)、コピー / 貼り付け / フィルの link 側面が
+     * 運ばれる。未宣言 = 素のセル、チョード素通し、Delete はテキストだけ書く。
+     */
+    getCellHyperlink?: (row: number, col: number) => string | undefined
+    /**
+     * OPTIONAL capability (v0.8): the cell's data-validation rule; undefined = none. Declared,
+     * an editor commit is validated (strict rules reject and fire onValidationRejected,
+     * non-strict rules only notify), visibly invalid cells carry `data-aqsp-invalid` (custom
+     * formulas are never evaluated at paint), list rules get the dropdown (Alt+ArrowDown) and
+     * the validation aspect of copy / paste / fill travels. Return a STABLE rule object per cell
+     * (identity) so the list-value intern hits. Absence = every commit passes as v0.7.
+     * 任意能力 (v0.8): セルのデータ検証規則。undefined = 無し。宣言時、エディタ確定は検証され
+     * (strict は拒否して onValidationRejected、非 strict は通知のみ)、目に見えて無効なセルは
+     * `data-aqsp-invalid` を持ち (custom 数式は描画時に評価しない)、list 規則はドロップダウン
+     * (Alt+ArrowDown) を持ち、コピー / 貼り付け / フィルの validation 側面が運ばれる。セル毎に
+     * **安定した**規則 object (identity) を返すと list 値の intern が当たる。未宣言 = 全確定が
+     * v0.7 どおり通る。
+     */
+    getCellValidation?: (row: number, col: number) => DataValidationRule | undefined
+    /**
+     * OPTIONAL capability (v0.8): the sheet-level conditional-format rules in PRIORITY order
+     * (array order = evaluation order; an earlier true rule wins per property, `stopIfTrue` ends
+     * the walk). Requires getCellFormat (declared alone ⇒ RangeError at mount). Return a stable
+     * array identity — the grid rebuilds its bucket index per (rules identity, renderVersion), so
+     * publish a rule change by bumping dataVersion. Declared, the CF aspect of copy / paste
+     * travels (pasted rules arrive as PasteEditContext.conditionalFormats). Absence = base
+     * formats paint as-is.
+     * 任意能力 (v0.8): シート水準の条件付き書式規則を**優先順** (配列順 = 評価順。先の真規則が
+     * プロパティ毎に勝ち、`stopIfTrue` で打ち切り) で返す。getCellFormat を要する (単独宣言は
+     * マウント時 RangeError)。配列 identity を安定させること — グリッドは (規則 identity,
+     * renderVersion) 毎にバケット索引を再構築するため、規則変更は dataVersion 増分で公開する。
+     * 宣言時、コピー / 貼り付けの CF 側面が運ばれる (貼り付けた規則は
+     * PasteEditContext.conditionalFormats で届く)。未宣言 = base 書式をそのまま塗る。
+     */
+    getConditionalFormats?: () => readonly ConditionalFormatRule[]
+    /**
+     * OPTIONAL capability (v0.8): the numeric minimum / maximum over a range, for colorScale
+     * rules whose end points omit `value`; null = the range holds no numeric value. Memoised by
+     * the grid per (rule id, renderVersion). Absence = such rules are skipped whole (rules with
+     * explicit values still paint).
+     * 任意能力 (v0.8): レンジ内の数値の最小 / 最大 — `value` 省略の端点を持つ colorScale 規則用。
+     * null = 数値が無い。グリッドが (規則 id, renderVersion) 毎に memo する。未宣言 = そのような
+     * 規則は丸ごとスキップ (値明示の規則は塗る)。
+     */
+    getRangeExtrema?: (range: CellRange) => { min: number; max: number } | null
+    /**
+     * OPTIONAL capability (v0.8): evaluates a formula string (passed VERBATIM, "=" included) in
+     * the context of `cell`; truth for a customFormula rule / custom validation = `true` or a
+     * finite non-zero number. Memoised by the grid per (rule id, row, col, renderVersion) for
+     * conditional formats; custom validation calls it at commit only (never at paint). Absence =
+     * customFormula rules are skipped and custom validation accepts.
+     * 任意能力 (v0.8): 数式文字列 ("=" を含め**そのまま**渡す) を `cell` の文脈で評価する。
+     * customFormula 規則 / custom 検証の真 = `true` または有限非 0 数。条件付き書式ではグリッドが
+     * (規則 id, row, col, renderVersion) 毎に memo し、custom 検証は確定時だけ呼ぶ (描画時は呼ばない)。
+     * 未宣言 = customFormula 規則はスキップ、custom 検証は通す。
+     */
+    evaluateFormula?: (formula: string, cell: CellCoord) => string | number | boolean | null
+}
+
+/**
+ * The ONE alignment judgment every alignment consumer shares (cell props, the in-cell editor's
+ * text-align, and any future surface), over the PAINTED format (base ⊕ conditional formats)
+ * rather than the adapter: an explicit `align` wins outright; otherwise the alignment is auto BY
+ * THE ACTUAL VALUE, so the text is read through `readText` — the eighth read of a cell, shared
+ * with CF conditions and the invalid marker via {@link lazyCellText} — only then. The
+ * getCellFormat capability branch (undeclared = the v0.1 identity: no alignment attribute at
+ * all, which is NOT the same as "left") lives at the caller: a painted format has no adapter to
+ * inspect, so the caller skips this judgment entirely when the capability is absent.
+ * 揃えの全消費者 (セル属性・セル内エディタの text-align・将来の面) が共有する唯一の揃え判定 —
+ * アダプタでなく**塗り書式** (base ⊕ 条件付き書式) に対して: 明示 `align` は無条件に勝ち、
+ * それ以外は**実際の値**による自動判定なので、そのときだけ `readText` で text を読む (セル
+ * 8 読み目 — {@link lazyCellText} で CF 条件 / 無効マーカーと共有)。getCellFormat の能力分岐
+ * (未宣言 = v0.1 恒等: 揃え属性そのものを出さない — 「左」とは別物) は呼び手側にある: 塗り書式
+ * には調べるべきアダプタが無いので、未宣言なら呼び手がこの判定自体を省く。
+ */
+export const resolveCellAlign = (painted: CellFormat | undefined, readText: () => string): CellAlign => {
+    // 塗り書式なし = 揃えも値書式も未指定 → 実際の値で自動判定 (8 読み目)
+    if (painted === undefined) {
+        return resolveAlign(undefined, undefined, readText())
+    }
+    // 明示 align があれば text 読み取り不要 (自動判定だけが実際の値を必要とする)
+    return resolveAlign(painted.align, painted.value, painted.align === undefined ? readText() : "")
+}
+
+/**
+ * Lazy once-only text thunk — the single construction point of a cell's eighth read, shared by
+ * alignment (align unset), conditional-format conditions and the visible-invalid check so the
+ * text is read at most ONCE per cell per slice. Nothing is read at construction; the first call
+ * reads getCellText and every later call returns that same string (an empty "" is a valid,
+ * cached value — the thunk never re-reads).
+ * 遅延 1 回読みの text thunk — セル 8 読み目の単一構築点。揃え (align 未設定)・条件付き書式の
+ * 条件・無効表示判定が共有し、text はスライス毎セル毎に最大 **1 回**しか読まれない。構築時には
+ * 読まず、初回呼び出しで getCellText を読み、以後は同じ文字列を返す (空文字 "" も正当なキャッシュ
+ * 値 — 再読はしない)。
+ */
+export const lazyCellText = (adapter: SpreadsheetDataAdapter, row: number, col: number): (() => string) => {
+    // 未読の番兵は null (空文字 "" は正当な値なので番兵に使わない)
+    let text: string | null = null
+    return () => {
+        if (text === null) {
+            text = adapter.getCellText(row, col)
+        }
+        return text
+    }
+}
+
+/**
+ * Editor seed text: the formula source when the getCellFormula capability is declared and the
+ * cell holds one (it must start with "=" — anything else, including a non-string, is a
+ * RangeError before dispatch, the findDataEdge precedent), else the canonical text. A capability
+ * branch, not a value fallback: without the capability getCellFormula is never consulted, and
+ * with a formula getCellText is not read.
+ * エディタ初期文字列: getCellFormula 能力が宣言され、セルに数式があればその数式ソース ("=" 始まり
+ * 必須 — それ以外は非文字列を含めディスパッチ前に RangeError、findDataEdge の前例)、それ以外は
+ * 正準文字列。能力分岐であって値フォールバックではない: 未宣言なら getCellFormula には触れず、
+ * 数式があれば getCellText は読まない。
+ */
+export const resolveEditText = (adapter: SpreadsheetDataAdapter, row: number, col: number): { text: string; isFormula: boolean } => {
+    // 能力分岐: getCellFormula 未宣言なら「数式」という概念自体が無い (v0.7 恒等)
+    if (adapter.getCellFormula !== undefined) {
+        const formula = adapter.getCellFormula(row, col)
+        if (formula !== undefined) {
+            // "=" 始まり以外は consumer のバグ — findDataEdge と同じくディスパッチ前に fail-fast
+            if (typeof formula !== "string" || !formula.startsWith("=")) {
+                throw new RangeError(`[spreadsheet] getCellFormula(${row}, ${col}) must return a string starting with "=", received ${JSON.stringify(formula)}`)
+            }
+            return { text: formula, isFormula: true }
+        }
+    }
+    return { text: adapter.getCellText(row, col), isFormula: false }
+}
+
+/**
+ * The declared aspect capabilities of an adapter — one boolean per rich-cell aspect, derived
+ * purely from which optional reads are declared ("what cannot be read cannot be written"):
+ * `format` = getCellFormat, `note` = getCellNote, `comments` = getCellComments, `hyperlink` =
+ * getCellHyperlink, `validation` = getCellValidation, `cf` = getConditionalFormats, `formula` =
+ * getCellFormula. findDataEdge is navigation, not an aspect.
+ * アダプタの宣言済み側面能力 — リッチセル側面毎に 1 真偽値、どの任意読みが宣言されているかだけ
+ * から導く (「読めないものは書けない」): `format` = getCellFormat、`note` = getCellNote、
+ * `comments` = getCellComments、`hyperlink` = getCellHyperlink、`validation` = getCellValidation、
+ * `cf` = getConditionalFormats、`formula` = getCellFormula。findDataEdge は航行であり側面ではない。
+ */
+export type AspectCapabilities = { format: boolean; note: boolean; comments: boolean; hyperlink: boolean; validation: boolean; cf: boolean; formula: boolean }
+
+/**
+ * Declared aspect capabilities (the write gate's single reader): the paste path strips every
+ * undeclared aspect before tiling, and commands and popovers are available only for declared
+ * aspects (their default chords pass through otherwise). A live read of the adapter (no memo)
+ * so the judgment is always the adapter's current declaration. The paint path (getCellProps)
+ * makes the same live judgment through direct member reads and never builds this snapshot —
+ * a per-cell allocation has no place on the paint hot path.
+ * 宣言済み側面能力 (書込ゲートの単一読み): 貼り付け経路は tiling 前に未宣言側面を除去し、
+ * コマンド / ポップオーバーは宣言済み側面でだけ利用可能 (それ以外は既定チョードが素通し)。
+ * アダプタの生読み (memo なし) なので判定は常にアダプタの現在の宣言。塗り経路 (getCellProps) は
+ * 同じ生判定をメンバー直接読みで行いこのスナップショットを組まない — セル毎割当は塗りの
+ * hot path に置かない。
+ */
+export const aspectCapabilities = (adapter: SpreadsheetDataAdapter): AspectCapabilities => ({
+    format: adapter.getCellFormat !== undefined,
+    note: adapter.getCellNote !== undefined,
+    comments: adapter.getCellComments !== undefined,
+    hyperlink: adapter.getCellHyperlink !== undefined,
+    validation: adapter.getCellValidation !== undefined,
+    cf: adapter.getConditionalFormats !== undefined,
+    formula: adapter.getCellFormula !== undefined,
+})