@aiquants/spreadsheet 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,1960 @@
+import { ForwardRefExoticComponent } from 'react';
+import { ProfilerOnRenderCallback } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+
+/** Border colour when `CellBorder.color` is absent (a stated default, not a fallback). / 罫線色の宣言済み既定 (fallback ではなく仕様上の既定)。 */
+export declare const BORDER_DEFAULT_COLOR = "#000000";
+
+/** Border preset vocabulary of `setBorders` (v0.8 §1.10). / setBorders のプリセット語彙 (v0.8 §1.10)。 */
+export declare type BorderPreset = "outer" | "all" | "clear" | "top" | "right" | "bottom" | "left";
+
+/**
+ * Structural normal form of a format, or undefined when nothing survives: `undefined` keys and
+ * `false` booleans are dropped (absent = default), border sides whose value is undefined are
+ * dropped and an empty `borders` disappears, unknown keys are dropped, nested objects (value /
+ * borders / each side) are rebuilt with undefined keys removed, and every object is emitted with
+ * its keys in SORTED order so `JSON.stringify` of the result is a deterministic interning key
+ * (copy dictionary, command memo). Values are NOT validated — an unparseable colour or a
+ * non-positive font size is kept verbatim and ignored fail-soft by the paint engine:
+ * canonicalization is about structure, not meaning. Always returns a fresh object (the input is
+ * never mutated) and is idempotent.
+ * 書式の構造的正準形 (何も残らなければ undefined)。undefined キーと false 真偽値は落とす (不在 =
+ * 既定)、値 undefined の辺は落とし空の borders は消え、未知キーは落ち、入れ子 (value / borders /
+ * 各辺) は undefined キーを除いて再構築、全 object をキー辞書順で出力するため `JSON.stringify`
+ * がそのまま決定的 intern キー (copy 辞書・コマンド memo)。値の検証はしない — 解釈不能な色や
+ * 非正のフォントサイズはそのまま残し塗りエンジンが fail-soft に無視: 正準化は意味でなく構造の話。
+ * 常に新規 object を返し (入力は不変)、冪等。
+ */
+export declare const canonicalizeFormat: (format: CellFormat) => CellFormat | undefined;
+
+/**
+ * @fileoverview Built-in cell display formatting (v0.7 — the getCellFormat capability). Pure,
+ * React-free value→string engine + horizontal-alignment resolver. The consumer declares a
+ * per-cell CellFormat via the optional adapter capability getCellFormat(row, col); the grid
+ * applies the value format to the DISPLAY string (editing / copy / TSV keep the raw
+ * getCellText) and the alignment to the flex cell's justify-content.
+ *
+ * Engine contract (each clause is load-bearing and mutation-gated — spec 07 §5.8):
+ * - EXACT decimal rendering: the validated raw string is handed to Intl.NumberFormat AS A
+ *   STRING (NumberFormat v3 mathematical values), never converted through a binary double —
+ *   so "1.45" with {type:"percent", scale:false, decimals:1} renders "1.5%" (not the drifted
+ *   "1.4%") and integers beyond 2^53 keep every digit. percent scale:false divides by 100 as
+ *   a pure string exponent shift, again without touching floating point. Literal exponents
+ *   are grammar-bounded to 4 digits (±9999) — past ICU's own limits, inputs stay raw.
+ * - INTERNED formatters: Intl.NumberFormat instances are cached per exact option tuple
+ *   (construction FAILURES are interned too) behind an identity WeakMap tier keyed on the
+ *   value-format object (an identity-stable adapter answer skips even the key build), so
+ *   per-cell rendering and autofit measurement never re-pay the ~40µs construction cost — nor
+ *   the per-cell key-build cost — per cell per slice.
+ * - Negative-zero suppression via signDisplay:"negative" (a value that rounds to zero never
+ *   shows a minus sign) — locale-proof, including non-ASCII numbering systems.
+ * - TOTAL fail-soft: a non-numeric string in a numeric format, an invalid date, or an
+ *   out-of-range Intl option (bad decimals / currency / locale) renders the raw text
+ *   unchanged — a header/label never breaks.
+ * - TRULY timezone-free dates: parsing/validation/rendering is pure integer calendar math
+ *   (leap-year aware) — no Date object is ever constructed, so host TZ, DST gaps, and the
+ *   two-digit-year remapping cannot affect which dates format or how.
+ * - Alignment "unset" is AUTO by the VALUE, not the declared format: text that actually
+ *   parses under the cell's numeric/date format (or as a strict decimal with no format)
+ *   resolves right, labels resolve left — the Excel / Google Sheets render-time default.
+ *
+ * 組み込みセル表示形式 (v0.7 — getCellFormat 能力)。純関数・React 非依存の値→文字列エンジン +
+ * 水平揃え解決。エンジン契約 (全て変異検証で封印 — spec 07 §5.8):
+ * 正確十進 (検証済み素文字列を Intl へ**文字列のまま**渡し二進浮動小数を経由しない —
+ * percent scale:false の ÷100 も文字列指数シフト)、interned フォーマッタ (構築失敗も
+ * インターンし、値書式 object キーの identity WeakMap 層でキー構築も省き、セル毎の Intl 構築
+ * コストを排除)、signDisplay:"negative" による負ゼロ抑止
+ * (非 ASCII 数字体系でも成立)、全経路 fail-soft (非数値 / 無効日付 / 範囲外オプションは素の
+ * text)、Date 非依存の純整数暦検証 (ホスト TZ / DST / 2 桁年写像の影響が構造的にゼロ)、
+ * align 未指定は**値による自動** — 実際に解釈できる値だけ右、ラベルは左 (Excel / Sheets の描画時既定)。
+ *
+ * v0.8 (rich cells) widens CellFormat to the full declarative cell format — vertical alignment,
+ * wrap, background / text colour, bold / italic / underline / strikethrough, font family / size
+ * (pt) and per-side borders — and adds the pure FORMAT ALGEBRA the commands and the clipboard
+ * share: canonicalizeFormat (the structural normal form — false booleans / undefined keys /
+ * empty borders dropped, every object emitted with SORTED keys so JSON.stringify of a canonical
+ * form is a deterministic interning key), mergeFormat (patch application with null = clear,
+ * identity-preserving when nothing changes so an unchanged cell emits no edit) and
+ * formatEquals (structural equality on canonical forms, key-order independent). Painting
+ * (CSS / attributes) lives in cellPaint.ts; this module stays a value model.
+ *
+ * v0.8 (リッチセル) は CellFormat を宣言的セル書式の全体 (縦揃え・折返し・背景 / 文字色・太字 /
+ * 斜体 / 下線 / 取消線・フォント族 / サイズ (pt)・辺毎の罫線) へ拡張し、コマンドとクリップボード
+ * が共有する純関数の書式代数を追加: canonicalizeFormat (構造的正準形 — false 真偽値 / undefined
+ * キー / 空 borders を落とし、全 object をキー辞書順で出力するため JSON.stringify がそのまま
+ * 決定的 intern キー)、mergeFormat (null = 消去のパッチ適用、無変化なら base を identity で返し
+ * 無変化セルは edit を出さない)、formatEquals (正準形の構造等価・キー順非依存)。塗り (CSS /
+ * 属性) は cellPaint.ts、本モジュールは値モデルに留まる。
+ */
+/** Horizontal cell alignment. / セルの水平揃え。 */
+export declare type CellAlign = "left" | "center" | "right";
+
+/** One border side: line style plus an optional colour (absent = BORDER_DEFAULT_COLOR). / 罫線 1 辺: 線種 + 任意の色 (省略 = BORDER_DEFAULT_COLOR)。 */
+export declare type CellBorder = {
+    style: CellBorderStyle;
+    color?: string;
+};
+
+/** Per-side borders of a cell (absent side = no border). / セルの辺毎の罫線 (辺の省略 = 罫線なし)。 */
+export declare type CellBorders = {
+    top?: CellBorder;
+    right?: CellBorder;
+    bottom?: CellBorder;
+    left?: CellBorder;
+};
+
+/** Border line style vocabulary (Excel / Sheets subset). / 罫線種の語彙 (Excel / Sheets 部分集合)。 */
+export declare type CellBorderStyle = "thin" | "medium" | "thick" | "dashed" | "dotted" | "double" | "hair";
+
+/**
+ * One comment as the consumer stores it (read side of `getCellComments`): every field is
+ * present because the consumer stamped it when the comment was created.
+ * consumer が保持するコメント 1 件 (getCellComments の読み側): 作成時に consumer が刻印するため
+ * 全フィールドが揃う。
+ */
+export declare type CellComment = {
+    id: string;
+    author: string;
+    text: string;
+    createdAt: string;
+};
+
+/**
+ * One comment as written through `CellPatch.comments` (the WHOLE thread travels): `id` present
+ * = keep that existing comment verbatim; `id` absent = a new comment whose id / author /
+ * createdAt the consumer mints (`author` / `createdAt` are carried only when a paste re-plays a
+ * foreign thread). A `CellComment` is assignable to this type as is, so a thread can be spread
+ * into a reply unchanged.
+ * CellPatch.comments で書かれるコメント 1 件 (スレッド全体を運ぶ): `id` あり = その既存コメントを
+ * verbatim に保持、`id` なし = 新規 (id / author / createdAt は consumer が採番 — author /
+ * createdAt は paste が外来スレッドを再生するときだけ載る)。`CellComment` はそのまま代入可能で、
+ * 既存スレッドを返信へ無変更で展開できる。
+ */
+export declare type CellCommentInput = {
+    id?: string;
+    text: string;
+    author?: string;
+    createdAt?: string;
+};
+
+/**
+ * @fileoverview Coordinate / range / operation vocabulary shared across the whole grid:
+ * cell-coordinate and range pure functions plus the public named unions (SpreadsheetDirection,
+ * SpreadsheetOperation). Every range in the system is a normalized rectangle built via
+ * makeRange.
+ *
+ * 座標・レンジ・操作の語彙: セル座標とレンジの純関数群 + 公開の名前つき union
+ * (SpreadsheetDirection / SpreadsheetOperation)。システム内の全レンジは makeRange で構築
+ * された正規化矩形。
+ */
+/** A single cell position (0-based). / 単一セル位置 (0 始まり)。 */
+export declare type CellCoord = {
+    row: number;
+    col: number;
+};
+
+/**
+ * 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 declare type CellEdit = {
+    row: number;
+    col: number;
+} & CellPatch;
+
+/**
+ * A cell's declared display format, returned per-cell by the adapter's getCellFormat capability
+ * (v0.8 — the full rich-cell vocabulary): value format (undefined = raw text), horizontal
+ * alignment (undefined = auto by the value), vertical alignment (undefined = middle), wrap,
+ * background / text colour (any CSS colour text — normalised by the paint engine, unparseable =
+ * ignored), bold / italic / underline / strikethrough (absent = false), font family, font size
+ * in POINTS (painted as pt × 4 / 3 px) and per-side borders. Every key is optional; the
+ * canonical form (canonicalizeFormat) is what the package writes back through CellEdit.format.
+ * セルの宣言済み表示形式 — アダプタの getCellFormat 能力がセル毎に返す (v0.8 — リッチセルの
+ * 全語彙): 値書式 (undefined = 素の文字列)・水平揃え (undefined = 値による自動)・垂直揃え
+ * (undefined = 中央)・折返し・背景 / 文字色 (任意の CSS 色文字列 — 塗りエンジンが正規化、解釈
+ * 不能は無視)・太字 / 斜体 / 下線 / 取消線 (不在 = false)・フォント族・フォントサイズ (pt 単位、
+ * pt × 4 / 3 px で描画)・辺毎の罫線。全キー任意。パッケージが CellEdit.format で書き戻すのは
+ * 正準形 (canonicalizeFormat)。
+ */
+export declare type CellFormat = {
+    value?: CellValueFormat;
+    align?: CellAlign;
+    verticalAlign?: CellVerticalAlign;
+    wrap?: boolean;
+    background?: string;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    borders?: CellBorders;
+};
+
+/**
+ * Command / handle input ONLY — never crosses the adapter. A key set to `null` CLEARS it, an
+ * omitted / undefined key leaves the base value untouched, any other value replaces it (borders
+ * are replaced as a whole set — callers spread the base sides to change one side).
+ * コマンド / handle 入力専用 — アダプタを跨がない。`null` のキーは消去、省略 / undefined は
+ * base の値を保持、それ以外は置換 (borders は辺の集合ごと置換 — 1 辺だけ変えるときは呼び手が
+ * base の辺を展開する)。
+ */
+export declare type CellFormatPatch = {
+    readonly [K in keyof CellFormat]?: CellFormat[K] | null;
+};
+
+/**
+ * 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 declare type CellPatch = {
+    text?: string;
+    format?: CellFormat | null;
+    note?: string | null;
+    comments?: readonly CellCommentInput[] | null;
+    hyperlink?: string | null;
+    validation?: DataValidationRule | null;
+};
+
+/**
+ * A normalized rectangular range (startRow <= endRow, startCol <= endCol). Construct ONLY via
+ * {@link makeRange}. / 正規化済み矩形レンジ。必ず {@link makeRange} で構築。
+ */
+export declare type CellRange = {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+};
+
+/** Numeric comparison when the text and the used bounds are strict decimals, else string comparison. / text と使う境界が厳密 10 進なら数値比較、他は文字列比較。 */
+export declare type CellValueCondition = {
+    type: "cellValue";
+    op: CompareOp;
+    a: string;
+    b?: string;
+};
+
+/**
+ * A value display format (type-based — "simple formats"). All fields optional beyond `type`,
+ * except `currency.currency` which is REQUIRED (a currency is meaningless without its code —
+ * the package stays host-agnostic and never assumes a region default).
+ * 値の表示形式 (型ベース・簡易形式)。`type` 以外は基本任意だが `currency.currency` のみ必須
+ * (通貨コードなしの通貨書式は無意味・パッケージは地域既定を仮定しないホスト非依存設計)。
+ */
+export declare type CellValueFormat = {
+    type: "number";
+    decimals?: number;
+    grouping?: boolean;
+    locale?: string;
+} | {
+    type: "percent";
+    decimals?: number;
+    scale?: boolean;
+    locale?: string;
+} | {
+    type: "currency";
+    currency: string;
+    decimals?: number;
+    locale?: string;
+} | {
+    type: "scientific";
+    decimals?: number;
+    locale?: string;
+} | {
+    type: "date";
+    pattern?: string;
+} | {
+    type: "text";
+};
+
+/** Vertical cell alignment (undefined = middle, the cell's flex centring). / セルの垂直揃え (undefined = 中央 = セルの flex 中央)。 */
+export declare type CellVerticalAlign = "top" | "middle" | "bottom";
+
+/** The condition vocabulary (six members). / 条件の語彙 (6 メンバー)。 */
+export declare type CfCondition = CellValueCondition | TextCondition | EmptyCondition | NotEmptyCondition | ColorScaleCondition | CustomFormulaCondition;
+
+/** Needle vocabulary of the `text` condition (exact, case-sensitive). / text 条件の needle 語彙 (完全一致・大文字小文字区別)。 */
+export declare type CfTextOp = "contains" | "notContains" | "startsWith" | "endsWith";
+
+/** The text must equal `checked` or `unchecked` (declared defaults "TRUE" / "FALSE"). / text が checked か unchecked と一致 (宣言済み既定は "TRUE" / "FALSE")。 */
+export declare type CheckboxValidationRule = {
+    type: "checkbox";
+    checked?: string;
+    unchecked?: string;
+};
+
+/**
+ * One cell on the wire: `t` raw text, `f` the formula in origin-relative R1C1 (`=` leading),
+ * `fmt` / `val` indexes into the payload dictionaries, `note`, the id-less `comments` thread and
+ * the hyperlink `link`. Absent keys are absent aspects.
+ * wire 上のセル 1 つ: `t` 素の文字列、`f` 原点相対 R1C1 の数式 (`=` 始まり)、`fmt` / `val` は
+ * payload 辞書への索引、`note`、id を剥がした `comments` スレッド、リンク `link`。不在キー =
+ * 不在側面。
+ */
+export declare type ClipCell = {
+    t: string;
+    f?: string;
+    fmt?: number;
+    val?: number;
+    note?: string;
+    comments?: readonly ClipComment[];
+    link?: string;
+};
+
+/** The channel a paste arrives on: the paste event (custom MIME available) or the async clipboard menu path. / 貼り付けの経路: paste イベント (カスタム MIME あり) か非同期クリップボードのメニュー経路。 */
+export declare type ClipChannel = "event" | "menu";
+
+/** A comment on the wire — the consumer's `id` is stripped (every pasted comment is new). / wire 上のコメント — consumer の `id` は剥がされる (貼り付けられたコメントは全件新規)。 */
+export declare type ClipComment = {
+    text: string;
+    author: string;
+    createdAt: string;
+};
+
+/**
+ * The common input of both channels: the available flavour types and a reader for one type.
+ * `getData` is called only for a type present in `types` and only when detection needs it —
+ * callers should memoise it per gesture when the read is expensive (a paste event's `getData`
+ * re-materialises the string on every call).
+ * 両経路の共通入力: 利用可能なフレーバー種別と 1 種別の読み手。`getData` は `types` に在る種別に
+ * だけ、検出が要するときにだけ呼ばれる — 読みが高価なとき (paste イベントの `getData` は呼ぶ度に
+ * 文字列を再実体化する) は呼び手がジェスチャ毎に memo する。
+ */
+export declare type ClipFlavours = {
+    types: readonly string[];
+    getData: (type: string) => string;
+};
+
+/** The armed clip surface a consumer sees (`onClipChange` / `getClip`): `foreign` = the record belongs to another adapter (sheet switch kept a cut). / consumer が見る装填クリップ (`onClipChange` / `getClip`): `foreign` = 記録が別アダプタのもの (シート切替が cut を保持)。 */
+export declare type ClipInfo = {
+    kind: "copy" | "cut";
+    range: CellRange;
+    foreign: boolean;
+};
+
+/**
+ * The lossless clip payload (wire format v1). The four leading keys are fixed in this order;
+ * `cells` is exactly `rows × cols`; `colWidths` / `rowHeights` travel only when the copy source
+ * was whole columns / whole rows; conditional-format inputs are origin-relative and clipped to
+ * the copied rectangle.
+ * lossless クリップ payload (wire format v1)。先頭 4 キーは固定順、`cells` は rows × cols ちょうど、
+ * `colWidths` / `rowHeights` は全列 / 全行 copy のときだけ、条件付き書式入力は原点相対でコピー
+ * 矩形に切り詰め済み。
+ */
+export declare type ClipPayload = {
+    v: 1;
+    rows: number;
+    cols: number;
+    clipId: string;
+    formats: readonly CellFormat[];
+    validations: readonly DataValidationRule[];
+    cells: readonly (readonly ClipCell[])[];
+    colWidths?: readonly number[];
+    rowHeights?: readonly number[];
+    wholeRows: boolean;
+    wholeCols: boolean;
+    conditionalFormats: readonly ConditionalFormatRuleInput[];
+};
+
+/** The detected clipboard source kind (ADR-14). / 検出されたクリップボードソース種別 (ADR-14)。 */
+export declare type ClipSource = "aqsp" | "sheets" | "excel" | "html" | "tsv" | "none";
+
+/** sRGB interpolation between two or three points over the numeric value; non-numeric text does not apply. / 数値に対する 2 点または 3 点の sRGB 補間。非数値 text は不適用。 */
+export declare type ColorScaleCondition = {
+    type: "colorScale";
+    min: ScalePoint;
+    mid?: ScalePoint;
+    max: ScalePoint;
+};
+
+/** Column index (0-based) to Excel-style name (0 → A, 26 → AA, 16383 → XFD). / 列 index → 列名。 */
+export declare const columnIndexToName: (index: number) => string;
+
+/** Excel-style name to column index (inverse). / 列名 → 列 index (逆変換)。 */
+export declare const columnNameToIndex: (name: string) => number;
+
+/**
+ * Renders the comment thread and the reply form for one cell.
+ * 1 セルのコメントスレッドと返信フォームを描画する。
+ */
+export declare const CommentPopover: ({ ctx, labels }: CommentPopoverProps) => ReactNode;
+
+/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。 */
+export declare type CommentPopoverContext = {
+    kind: "comment";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: readonly CellComment[];
+    commit: (next: readonly CellCommentInput[] | null) => void;
+    close: () => void;
+    rejected: boolean;
+};
+
+export declare type CommentPopoverProps = {
+    ctx: CommentPopoverContext;
+    labels: SpreadsheetLabels;
+};
+
+/** Ordered comparison vocabulary of `cellValue` (the same eight words as the validation engine); between / notBetween include both bounds. / cellValue の比較語彙 (検証エンジンと同じ 8 語)。between / notBetween は両端含み。 */
+export declare type CompareOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "notBetween";
+
+/** One rule as the consumer stores it: consumer-scoped `id`, the ranges it applies to, its condition, the style it paints, and whether a match ends the walk. / consumer が保持する規則 1 件: consumer スコープの id、適用レンジ、条件、塗る style、真で打ち切るか。 */
+export declare type ConditionalFormatRule = {
+    id: string;
+    ranges: readonly CellRange[];
+    condition: CfCondition;
+    style: ConditionalFormatStyle;
+    stopIfTrue?: boolean;
+};
+
+/** One rule as a paste hands it to the consumer (`PasteEditContext.conditionalFormats`): the source rule's id travels as `sourceRuleId`, the consumer mints the new id. / paste が consumer へ渡す規則 1 件: 元規則の id は sourceRuleId、新 id は consumer が採番。 */
+export declare type ConditionalFormatRuleInput = {
+    sourceRuleId: string;
+    ranges: readonly CellRange[];
+    condition: CfCondition;
+    style: ConditionalFormatStyle;
+    stopIfTrue?: boolean;
+};
+
+/** The Sheets subset a rule may paint: background / colour / four text traits. Borders, alignment and number formats are out of scope (deviation row). / 規則が塗れる Sheets 部分集合: 背景 / 文字色 / 4 つの文字特性。罫線・揃え・数値書式は範囲外 (逸脱行)。 */
+export declare type ConditionalFormatStyle = {
+    background?: string;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+};
+
+/** `adapter.evaluateFormula(formula, cell)` verbatim; truth = `true` or a finite non-zero number. / evaluateFormula(formula, cell) を原文のまま。真 = true か有限非 0 数。 */
+export declare type CustomFormulaCondition = {
+    type: "customFormula";
+    formula: string;
+};
+
+/** The consumer's formula decides; evaluated only when the caller supplies `evaluate` (commit time). / consumer の数式が判定。呼び手が evaluate を渡すとき (確定時) だけ評価。 */
+export declare type CustomValidationRule = {
+    type: "custom";
+    formula: string;
+};
+
+/** A per-cell data-validation rule: the shared options intersected with one of the seven typed members (§1.2). / セル毎のデータ検証規則。共通オプションと 7 種の型付きメンバーの交差 (§1.2)。 */
+export declare type DataValidationRule = ValidationRuleBase & (ListValidationRule | NumberValidationRule | TextLengthValidationRule | DateValidationRule | TextValidationRule | CheckboxValidationRule | CustomValidationRule);
+
+/** The text must be a pure-calendar date satisfying `op` against the date-string bounds `a` (and `b`). / text が純暦日付で、日付文字列の境界 a (と b) に対し op を満たす。 */
+export declare type DateValidationRule = {
+    type: "date";
+    op: ValidationCompareOp;
+    a: string;
+    b?: string;
+};
+
+/** Default custom colour slots (v0.8 §1.9) for `fillColorCustom1..5` / `fontColorCustom1..5`. / カスタム色 5 スロットの既定 (v0.8 §1.9)。 */
+export declare const DEFAULT_CUSTOM_COLORS: readonly string[];
+
+/** Default band palette (plan §1.9) — the same values the `.aqsp-root` CSS variables fall back to. / 既定の帯パレット (計画 §1.9) — `.aqsp-root` の CSS 変数既定と同値。 */
+export declare const DEFAULT_HIGHLIGHT_COLORS: HighlightColors;
+
+/**
+ * English defaults for every key. `sinkAriaLabel` / `rootAriaLabel` are byte-identical to the
+ * v0.7 prop defaults (the fold is DOM-identical); `noteEscapeHint` = "Escape saves and closes";
+ * `commentCount` and `listMore` pluralise ("1 comment" / "n comments", "1 more value" / "n more values"). Frozen.
+ * 全キーの英語既定。`sinkAriaLabel` / `rootAriaLabel` は v0.7 の prop 既定と byte 同一 (畳込みは
+ * DOM 恒等)、`noteEscapeHint` = "Escape saves and closes"、`commentCount` / `listMore` は単複を区別。凍結済み。
+ */
+export declare const DEFAULT_LABELS: SpreadsheetLabels;
+
+/**
+ * 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 declare const DEFAULT_SHORTCUTS: ShortcutMap;
+
+/**
+ * Detects the ONE source a paste reads (ADR-14, design v5): event channel — `types` contains
+ * the custom MIME ⇒ `aqsp` (nothing else is read); then, on both channels, the first
+ * CLIP_DETECT_PREFIX_BYTES of `text/html` are scanned for markers (`aqsp` → `sheets` → `excel`)
+ * and the FULL text is tested for `<table` — a marker refines the kind, `<table` alone is
+ * `html`, and an HTML flavour without any table is not a table source at all; then a non-empty
+ * `text/plain` ⇒ `tsv`; else `none`. Never tries a reader; `getData` is called only for the
+ * flavours the decision needs and never for a type absent from `types`.
+ * 貼り付けが読む唯一のソースを検出 (ADR-14、設計 v5): event 経路 — `types` にカスタム MIME が
+ * 在れば `aqsp` (他は読まない)。次に両経路で `text/html` の先頭 CLIP_DETECT_PREFIX_BYTES を
+ * マーカー走査 (`aqsp` → `sheets` → `excel`) し全文を `<table` で判定 — マーカーは種別を精密化、
+ * `<table` だけなら `html`、表の無い HTML フレーバーは表ソースにならない。次に非空 `text/plain` ⇒
+ * `tsv`、他は `none`。reader は試行しない。`getData` は判定が要するフレーバーにだけ、`types` に
+ * 無い種別には決して呼ばない。
+ */
+export declare const detectClipSource: (flavours: ClipFlavours, channel: ClipChannel) => ClipSource;
+
+/**
+ * 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 declare type EditContext = PlainEditContext | PasteEditContext;
+
+/**
+ * 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 — あり得ない組合せは型が拒む。
+ */
+export declare type EditRejection = {
+    source: "edit";
+    editSession: "kept" | "discarded";
+} | {
+    source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate";
+};
+
+/**
+ * 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 declare type EditSource = "edit" | "paste" | "fill" | "delete" | "format" | "calc" | "annotate";
+
+/** The text is the empty string. / text が空文字。 */
+export declare type EmptyCondition = {
+    type: "empty";
+};
+
+/**
+ * Enumerates the union of ranges exactly once per cell (row-major).
+ * レンジ群の和集合をセル単位で**重複なく**行優先順に列挙する単一シーム。Delete のような
+ * 「レンジ列挙由来」の編集で同一セルの無意味な二重編集を作らないためのもの (cut → paste が
+ * **意図的に**積む重複 (後勝ち) とは別問題 — そちらは applyEdits の順序契約が扱う)。
+ */
+export declare const enumerateRangeCells: (ranges: readonly CellRange[], visit: (cell: CellCoord) => void) => void;
+
+/** Paste cell count WITHOUT materializing (ADR-12 pre-check). / 展開せず貼り付け対象セル数を見積もる (ADR-12 の事前検査)。 */
+export declare const estimatePasteCellCount: (source: readonly (readonly string[])[], target: CellRange) => number;
+
+/**
+ * Expands a paste into cell edits per the §6.5.3 table (copy path — silent grid-edge clip).
+ * Delegates to `tileCells` (v0.8) — output identical to the v0.7 flat loop.
+ * §6.5.3 の表どおり貼り付けを CellEdit 列へ展開 (copy 経路 — グリッド外は静かに切り捨て)。
+ * `tileCells` へ委譲 (v0.8) — 出力は v0.7 のフラットループと同一。
+ */
+export declare const expandPaste: (source: readonly (readonly string[])[], target: CellRange, active: CellCoord, rowCount: number, colCount: number) => CellEdit[];
+
+/**
+ * Formats the raw canonical text for DISPLAY per a value format. undefined / {type:"text"} /
+ * empty text pass through unchanged; a non-numeric string in a numeric format, an invalid date,
+ * or an out-of-range Intl option fails soft to the raw text. The validated decimal STRING is
+ * handed to Intl (exact — no double conversion), and percent scale:false pre-divides by 100 via
+ * a string exponent shift. Editing / copy never call this (they use the raw text).
+ * 素の正準文字列を値書式に従い表示用へ整形。undefined / {type:"text"} / 空文字は無変更で素通し。
+ * 数値書式の非数値・無効日付・範囲外 Intl オプションは素の text へ fail-soft。検証済み 10 進は
+ * **文字列のまま** Intl へ (double 変換なしの正確十進)、percent scale:false は文字列指数シフトで
+ * ÷100。編集 / コピーは呼ばない (素の値)。
+ */
+export declare const formatCellValue: (text: string, value: CellValueFormat | undefined) => string;
+
+/**
+ * Structural equality of two formats on their canonical forms — key order, undefined keys,
+ * false booleans and empty borders never matter; every value (including each border side and
+ * the nested value format) must match. `undefined` equals any format whose canonical form is
+ * empty.
+ * 正準形上の構造等価 — キー順・undefined キー・false 真偽値・空 borders は無関係、全値 (罫線の
+ * 各辺・入れ子の値書式を含む) が一致すること。`undefined` は正準形が空の書式と等しい。
+ */
+export declare const formatEquals: (a: CellFormat | undefined, b: CellFormat | undefined) => boolean;
+
+/** What `evaluateFormula` may answer. / evaluateFormula が返し得る値。 */
+export declare type FormulaValue = string | number | boolean | null;
+
+/**
+ * Resolves an R1C1 formula to A1 at `origin` — the paste side of {@link toR1C1}. A relative
+ * offset landing below row / column 0 becomes `#REF!` (behind its verbatim sheet part); text
+ * the R1C1 grammar rejects (`R0C1`, `R[+1]`, `R[1`) stays verbatim. Parsed forms are memoised
+ * per distinct string, so a 100k-cell paste of ≤ 100 distinct formulas parses ≤ 100 times.
+ * Non-formula text returns the same string instance; an invalid origin is a RangeError.
+ * R1C1 数式を `origin` で A1 へ解決 — {@link toR1C1} の貼り付け側。行 / 列 0 未満へ落ちる相対
+ * 差分は (原文シート部つきの) `#REF!`、R1C1 文法が拒む文字列 (`R0C1` / `R[+1]` / `R[1`) は
+ * 原文のまま。解析形は相異なる文字列毎にメモされ、≤ 100 種の数式の 10 万セル貼り付けは解析
+ * ≤ 100 回。非数式は同一文字列インスタンス、不正な原点は RangeError。
+ */
+export declare const fromR1C1: (r1c1: string, origin: CellCoord) => string;
+
+/** Band colours + shared opacity, written to `--aqsp-band-*` by ONE layout effect (never per frame). / 帯の色 + 共通不透明度 (`--aqsp-band-*` へ layout effect が 1 回書く — 毎フレームは書かない)。 */
+export declare type HighlightColors = {
+    row: string;
+    column: string;
+    intersection: string;
+    opacity: number;
+};
+
+/** Row / column / intersection highlight switches (v0.8 §2.4 — default all off = zero band nodes). / 行 / 列 / 交点強調のスイッチ (v0.8 §2.4 — 既定全 off = 帯ノード 0)。 */
+export declare type HighlightState = {
+    row: boolean;
+    column: boolean;
+    intersection: boolean;
+};
+
+/** The table kinds the reader accepts — the marker-detected `ClipSource` values that are HTML tables. / reader が受ける表の種別 — HTML 表であるマーカー検出済み `ClipSource` 値。 */
+export declare type HtmlTableKind = "sheets" | "excel" | "html";
+
+/**
+ * The outcome of `parseHtmlTable`: the payload of the first table; `limit` when the table would
+ * materialise more than the caller's `maxCells` (`cells` = the lower bound of `rows × cols` at
+ * which the reader stopped — already above the cap); `none` when there is no table, no row or no
+ * cell column.
+ * `parseHtmlTable` の結果: 最初の表の payload。`limit` は表が呼び手の `maxCells` を超えて実体化する
+ * とき (`cells` = reader が止まった時点の `rows × cols` の下界 — 既に上限超)。`none` は表 / 行 /
+ * セル列が無いとき。
+ */
+export declare type HtmlTableResult = {
+    readonly outcome: "payload";
+    readonly payload: ClipPayload;
+} | {
+    readonly outcome: "limit";
+    readonly cells: number;
+} | {
+    readonly outcome: "none";
+};
+
+/**
+ * Renders the hyperlink editor for one cell.
+ * 1 セルのハイパーリンクエディタを描画する。
+ */
+export declare const LinkPopover: ({ ctx, labels }: LinkPopoverProps) => ReactNode;
+
+/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。 */
+export declare type LinkPopoverContext = {
+    kind: "link";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: {
+        text: string;
+        url: string | undefined;
+    };
+    commit: (next: {
+        text: string;
+        url: string | null;
+    }) => void;
+    close: () => void;
+    canOpen: boolean;
+    open: () => void;
+    rejected: boolean;
+};
+
+export declare type LinkPopoverProps = {
+    ctx: LinkPopoverContext;
+    labels: SpreadsheetLabels;
+};
+
+/**
+ * Renders the list picker for one cell.
+ * 1 セルのリスト選択を描画する。
+ */
+export declare const ListPopover: ({ ctx, labels }: ListPopoverProps) => ReactNode;
+
+/** Validation list picker context: `current` = the list rule's values, `typed` = the prefix that opened it. / 検証リスト文脈: current = list 規則の値、typed = 開いたときの入力プレフィックス。 */
+export declare type ListPopoverContext = {
+    kind: "list";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: readonly string[];
+    typed: string;
+    commit: (value: string) => void;
+    close: () => void;
+};
+
+export declare type ListPopoverProps = {
+    ctx: ListPopoverContext;
+    labels: SpreadsheetLabels;
+};
+
+/** The text must equal one of `values` exactly; `showDropdown` is a UI hint only. / text が values のいずれかと完全一致。showDropdown は UI ヒントのみ。 */
+export declare type ListValidationRule = {
+    type: "list";
+    values: readonly string[];
+    showDropdown?: boolean;
+};
+
+/** Builds a normalized range from two corners. / 2 隅から正規化レンジを構築。 */
+export declare const makeRange: (a: CellCoord, b: CellCoord) => CellRange;
+
+/**
+ * Applies a patch to a base format: `null` clears a key, `undefined` (or an omitted key) keeps
+ * the base value, anything else replaces it (borders as a whole set). Returns the CANONICAL
+ * merged format — or `base` BY IDENTITY when the result is structurally unchanged (so callers
+ * skip the edit for an unchanged cell), or `undefined` when everything has been cleared. The
+ * base is never mutated.
+ * base 書式へパッチを適用: `null` はキー消去、`undefined` (省略) は base の値を保持、それ以外は
+ * 置換 (borders は集合ごと)。戻り値は**正準**の合成書式 — 構造的に無変化なら `base` を
+ * **identity で**返し (無変化セルの edit を呼び手が省ける)、全て消えれば `undefined`。base は
+ * 変更しない。
+ */
+export declare const mergeFormat: (base: CellFormat | undefined, patch: CellFormatPatch) => CellFormat | undefined;
+
+/**
+ * Renders the validation message.
+ * 検証メッセージを描画する。
+ */
+export declare const MessagePopover: ({ ctx, labels }: MessagePopoverProps) => ReactNode;
+
+/** Validation message context (input message or a strict rejection). / 検証メッセージ文脈 (入力メッセージまたは strict 拒否)。 */
+export declare type MessagePopoverContext = {
+    kind: "message";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: {
+        title: string;
+        message: string;
+        rejected: boolean;
+    };
+    close: () => void;
+};
+
+export declare type MessagePopoverProps = {
+    ctx: MessagePopoverContext;
+    labels: SpreadsheetLabels;
+};
+
+/**
+ * Normalises a hyperlink candidate: trims, parses it with the WHATWG URL parser (no base URL —
+ * a relative path, a bare host or an empty string is not a link), keeps only the allow-listed
+ * schemes and returns the parser's serialisation (`href`: scheme and host lower-cased, an
+ * `http(s)` origin gets its `/` path). Anything else is null — dropped at parse time, never
+ * navigated, never substituted.
+ * リンク候補の正規化: トリム → WHATWG URL 解析 (基点 URL なし — 相対パス・裸のホスト・空文字は
+ * リンクでない) → 許可スキームのみ → パーサの直列化 (`href`: スキームとホストは小文字、http(s) の
+ * origin には `/` パスが付く)。他は null — 解析時に落とし、航行も代替もしない。
+ */
+export declare const normalizeHyperlink: (text: string) => string | null;
+
+/** The text is not the empty string. / text が空文字でない。 */
+export declare type NotEmptyCondition = {
+    type: "notEmpty";
+};
+
+/**
+ * Renders the note editor for one cell.
+ * 1 セルの note エディタを描画する。
+ */
+export declare const NotePopover: ({ ctx, labels }: NotePopoverProps) => ReactNode;
+
+/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。 */
+export declare type NotePopoverContext = {
+    kind: "note";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: string | undefined;
+    commit: (next: string | null) => void;
+    close: () => void;
+    rejected: boolean;
+};
+
+export declare type NotePopoverProps = {
+    ctx: NotePopoverContext;
+    labels: SpreadsheetLabels;
+};
+
+/**
+ * Renders the note tip text.
+ * note tip の本文を描画する。
+ */
+export declare const NoteTip: ({ ctx }: NoteTipProps) => ReactNode;
+
+/** Hover note tip context (read-only). / ホバー note tip 文脈 (読み取り専用)。 */
+export declare type NoteTipContext = {
+    kind: "note-tip";
+    cell: CellCoord;
+    anchorRect: PopoverRect;
+    current: string;
+    close: () => void;
+};
+
+export declare type NoteTipProps = {
+    ctx: NoteTipContext;
+    labels: SpreadsheetLabels;
+};
+
+/**
+ * Host declarations consulted while decoding: `currency` = the code a BARE currency symbol
+ * denotes (undeclared ⇒ such patterns are dropped), `locale` = the rendering locale stamped on
+ * decoded numeric formats (an LCID-tagged currency carries its own locale instead).
+ * 復号時に参照するホスト宣言: `currency` = 裸の通貨記号が指す通貨コード (未宣言なら該当パターンは
+ * 省略)、`locale` = 復号した数値書式へ刻む描画 locale (LCID 付き通貨は自身の locale を持つ)。
+ */
+export declare type NumberFormatDecodeOptions = {
+    readonly currency?: string;
+    readonly locale?: string;
+};
+
+/** The text must be a strict decimal satisfying `op` against the decimal-string bounds `a` (and `b` for between / notBetween). / text が厳密 10 進で、10 進文字列の境界 a (between 系は b も) に対し op を満たす。 */
+export declare type NumberValidationRule = {
+    type: "number";
+    op: ValidationCompareOp;
+    a: string;
+    b?: string;
+};
+
+/**
+ * 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 declare const parseChord: (chord: string) => ParsedChord;
+
+/**
+ * Parses a wire-format string with TOTAL validation (fileoverview): null on any malformed input,
+ * never a partial payload, never a substituted value.
+ * wire format 文字列を全域検証つきで parse (fileoverview): 不正入力は全て null、部分 payload も
+ * 値の代替も無し。
+ */
+export declare const parseClipPayload: (json: string) => ClipPayload | null;
+
+/** A canonical chord decomposed: modifier flags + KEY token (`"A".."Z"` or a code name). / 正準チョードの分解形: 修飾フラグ + KEY トークン (`"A".."Z"` または code 名)。 */
+export declare type ParsedChord = {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    key: string;
+};
+
+/**
+ * Parses an Excel / Sheets / generic HTML clipboard string into a ClipPayload (the fileoverview
+ * reader contract). `kind` is the marker-detected source (`detectClipSource`), `options` the host's
+ * declared currency / locale for number-format decoding, `maxCells` the ADR-12 cap the reader
+ * itself enforces (a positive integer — anything else is a RangeError, an API surface, thrown
+ * before the DOMParser is built). TOTAL fail-soft on the markup: any string yields `payload`,
+ * `limit` or `none` — a blow-up of the ENVIRONMENT's own parser (an engine recursion limit on
+ * pathologically deep nesting) resolves `none` too; a payload is always valid for
+ * `serializeClipPayload`. Callers build the
+ * DOMParser only under the ADR-12 estimate and re-gate the payload's `rows × cols` with their
+ * tiling.
+ * Excel / Sheets / 汎用 HTML のクリップボード文字列を ClipPayload へ解析 (fileoverview の reader 契約)。
+ * `kind` はマーカー検出済みソース (`detectClipSource`)、`options` は数値書式復号用のホスト宣言
+ * (通貨 / locale)、`maxCells` は reader 自身が守る ADR-12 上限 (正整数 — 他は DOMParser 構築前に
+ * RangeError、API 面)。マークアップに対しては全域 fail-soft: 任意の文字列に `payload` / `limit` /
+ * `none` — 環境の parser 自身の破綻 (病的な入れ子深さでのエンジン再帰限界) も `none` に畳む。payload は
+ * 常に `serializeClipPayload` に有効。呼び手は ADR-12 見積もり下でだけ DOMParser
+ * を作り、payload の `rows × cols` をタイル込みで再ゲートする。
+ */
+export declare const parseHtmlTable: (html: string, kind: HtmlTableKind, options: NumberFormatDecodeOptions, maxCells: number) => HtmlTableResult;
+
+/**
+ * Parses Excel-behavior TSV into a rectangular matrix (ragged rows are right-padded).
+ * Excel 実挙動 TSV を矩形行列へ解析 (ギザギザ行は右パディング)。
+ */
+export declare const parseTsv: (text: string) => string[][];
+
+/**
+ * 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 declare type PasteEditContext = {
+    transaction: number;
+    source: "paste";
+    sameSheet: boolean;
+    conditionalFormats: readonly ConditionalFormatRuleInput[];
+};
+
+/** The paste-special modes (Excel Paste Special ∪ Sheets Paste special, §1.7). / 貼り付けスペシャルのモード (§1.7)。 */
+export declare type PasteMode = "all" | "values" | "formats" | "formulas" | "noBorders" | "columnWidths" | "validation" | "conditionalFormats" | "commentsAndNotes";
+
+/** Excel's Paste Special operation — the copied value is the RIGHT operand. / Excel の演算 — コピー値が右オペランド。 */
+export declare type PasteOperation = "add" | "subtract" | "multiply" | "divide";
+
+/**
+ * One paste gesture's options (§1.7): the mode, an optional arithmetic operation on the text
+ * aspect, skip-blanks, transpose and the inject-into-empty format option.
+ * 1 回の貼り付けのオプション (§1.7): モード、text 側面への任意の演算、空白スキップ、転置、
+ * 空セルへの書式注入。
+ */
+export declare type PasteOptions = {
+    mode: PasteMode;
+    operation?: PasteOperation;
+    skipBlanks?: boolean;
+    transpose?: boolean;
+    injectIntoEmpty?: boolean;
+};
+
+/** One paste's outcome: the adapter was called / nothing was written / refused (§1.10 `paste`). / 1 回の貼り付けの結果: アダプタが呼ばれた / 何も書かなかった / 拒否 (§1.10 `paste`)。 */
+export declare type PasteOutcome = "applied" | "empty" | "rejected";
+
+/**
+ * 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 declare type PlainEditContext = {
+    transaction: number;
+    source: "edit" | "fill" | "delete" | "format" | "calc" | "annotate";
+};
+
+/** The discriminated popover context handed to `renderPopover` / the default components (v0.8 §1.8). / renderPopover / 既定コンポーネントへ渡す判別文脈 (v0.8 §1.8)。 */
+export declare type PopoverContext = NotePopoverContext | NoteTipContext | CommentPopoverContext | LinkPopoverContext | ListPopoverContext | MessagePopoverContext;
+
+/** The six popover kinds (v0.8 §1.8). / 6 種のポップオーバー (v0.8 §1.8)。 */
+export declare type PopoverKind = "note" | "note-tip" | "comment" | "link" | "list" | "message";
+
+/** The `popovers` prop: `false` disables a kind (its commands pass through, `openPopover` throws). / `popovers` prop: `false` はその kind を無効化 (コマンドは素通し、`openPopover` は RangeError)。 */
+export declare type PopoverOverrides = {
+    readonly [K in PopoverKind]?: boolean;
+};
+
+/** A rectangle in the popover layer's coordinate space (logical viewport px). / ポップオーバー層座標系 (論理 viewport px) の矩形。 */
+export declare type PopoverRect = {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};
+
+/** Whether the range contains the cell. / レンジがセルを含むか。 */
+export declare const rangeContains: (range: CellRange, cell: CellCoord) => boolean;
+
+/** Numeric extrema of a range (the `getRangeExtrema` answer). / レンジの数値極値 (getRangeExtrema の答え)。 */
+export declare type RangeExtrema = {
+    min: number;
+    max: number;
+};
+
+/** Row/column extents of a range. / レンジの行数・列数。 */
+export declare const rangeSize: (range: CellRange) => {
+    rows: number;
+    cols: number;
+};
+
+/** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
+export declare type RenderCellContext = {
+    row: number;
+    col: number;
+    text: string;
+};
+
+/**
+ * The single read point: resolves one label to its display string. A function-valued label is
+ * called with `n` (a missing `n` is a caller bug ⇒ RangeError — no silent 0); a string label is
+ * returned as-is and ignores `n`.
+ * 唯一の読み出し点: ラベル 1 件を表示文字列へ解決。関数値は n で呼ぶ (n 省略は呼び手バグとして
+ * RangeError — 黙って 0 にしない)、文字列値はそのまま (n は無視)。
+ */
+export declare const resolveLabel: (labels: SpreadsheetLabels, key: keyof SpreadsheetLabels, n?: number) => string;
+
+/** One colour-scale point; `value` omitted = the range extremum from `getRangeExtrema` (min / max) or the arithmetic midpoint (mid). / 色スケールの 1 点。value 省略 = getRangeExtrema のレンジ極値 (min / max) か算術中点 (mid)。 */
+export declare type ScalePoint = {
+    color: string;
+    value?: number;
+};
+
+/**
+ * Options for the programmatic {@link SpreadsheetHandle.scrollToCell} jump — the render-surface
+ * pass-through of the engine's cell-targeted scroll (alignX uses start/end/center, alignY uses
+ * top/bottom/center; a frozen column/row target is a no-op on that axis). Selection is NOT
+ * changed — this is a pure viewport jump.
+ * 命令的セルジャンプ ({@link SpreadsheetHandle.scrollToCell}) のオプション (エンジンのセル狙い
+ * スクロールの素通し)。alignX は start / end / center、alignY は top / bottom / center。凍結列 /
+ * 行狙いは当該軸で no-op。選択は変えない純粋な viewport ジャンプ。
+ * 明示構造型で宣言する (api-extractor は NonNullable<Parameters<...>> 派生を d.ts ロールアップ
+ * できず build が落ちる) — エンジン型との双方向一致は Spreadsheet.spec.tsx の型パリティガードが
+ * tsc で機械封印する (ズレたら型検査が即赤)。
+ */
+export declare type ScrollToCellOptions = {
+    alignY?: "top" | "bottom" | "center";
+    alignX?: "start" | "end" | "center";
+    offsetX?: number;
+    offsetY?: number;
+};
+
+/** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
+export declare type SelectionState = {
+    /** Non-contiguous range list; the tail is the "current range". / 非連続選択のレンジ列 (末尾が現在レンジ)。 */
+    ranges: readonly CellRange[];
+    /** Drag / Shift-extend origin. / ドラッグ / Shift 拡張の起点。 */
+    anchor: CellCoord;
+    /** Active cell; never moved by extend operations (Excel semantics). / アクティブセル (拡張で不動)。 */
+    active: CellCoord;
+};
+
+/**
+ * Serialises a payload with the FIXED leading key order `{"v":1,"rows":R,"cols":C,"clipId":"…",…}`
+ * and a deterministic key order everywhere below (fileoverview). A structurally malformed
+ * payload (the parser's validation contract) is a RangeError — the serialiser never emits a
+ * string `parseClipPayload` would reject.
+ * 固定先頭キー順 `{"v":1,"rows":R,"cols":C,"clipId":"…",…}` と以下全階層の決定的キー順で直列化
+ * (fileoverview)。構造的に不正な payload (parser の検証契約) は RangeError — `parseClipPayload`
+ * が拒む文字列を直列化器は決して出さない。
+ */
+export declare const serializeClipPayload: (payload: ClipPayload) => string;
+
+/**
+ * Serializes a clip payload to the interop HTML table (see the fileoverview writer contract).
+ * `clipJson` is the payload's `serializeClipPayload` string (the caller already holds it for the
+ * custom MIME flavour) and becomes the FIRST attribute of `<table>`. A payload whose `cells`
+ * matrix is not `rows × cols` is a RangeError (consumer input on an API surface).
+ * クリップ payload を相互運用 HTML 表へ直列化 (fileoverview の writer 契約)。`clipJson` は payload の
+ * `serializeClipPayload` 文字列 (呼び手はカスタム MIME 用に既に持つ) で `<table>` の先頭属性になる。
+ * `cells` が `rows × cols` でない payload は RangeError (API 面の消費者入力)。
+ */
+export declare const serializeHtmlTable: (payload: ClipPayload, clipJson: string) => string;
+
+/**
+ * Serializes a matrix to Excel-behavior TSV with a trailing CRLF.
+ * 行列を終端 CRLF つきの Excel 実挙動 TSV へ直列化。
+ */
+export declare const serializeTsv: (matrix: readonly (readonly string[])[]) => string;
+
+/**
+ * Shifts the relative parts of every reference by (dRow, dCol) — the paste-offset transform.
+ * Absolute (`$`) parts stay; a reference shifted below row / column 0 becomes `#REF!` (behind
+ * its verbatim sheet part). Non-formula text and reference-free formulas return the same
+ * string instance. Non-integer deltas are a RangeError.
+ * 全参照の相対部を (dRow, dCol) だけシフト — 貼り付けオフセット変換。絶対 (`$`) 部は不変、
+ * 行 / 列 0 未満へ出た参照は (原文シート部つきの) `#REF!`。非数式・参照なし数式は同一文字列
+ * インスタンス。非整数の差分は RangeError。
+ */
+export declare const shiftFormula: (formula: string, dRow: number, dCol: number) => string;
+
+/** Command → canonical chords (empty = unbound; several chords allowed). / コマンド → 正準チョード群 (空 = 未束縛、複数可)。 */
+export declare 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 declare type ShortcutOverrides = {
+    readonly [K in SpreadsheetCommand]?: readonly string[] | null;
+};
+
+/**
+ * The spreadsheet root component (wiring only).
+ * スプレッドシート統合ルート (結線のみ)。
+ */
+export declare const Spreadsheet: ForwardRefExoticComponent<SpreadsheetProps & SpreadsheetTestProps & RefAttributes<SpreadsheetHandle>>;
+
+/**
+ * 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 declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
+
+/**
+ * @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 declare type 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";
+
+/**
+ * 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 declare 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;
+};
+
+/**
+ * Grid navigation direction (public vocabulary). Package-prefixed: a bare `Direction` would
+ * clash with consumer-side types of the same name.
+ * グリッド航行方向 (公開語彙)。素の `Direction` は consumer 側の同名型と衝突しやすいため
+ * パッケージ接頭辞つき。
+ */
+export declare type SpreadsheetDirection = "up" | "down" | "left" | "right";
+
+/** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
+export declare type SpreadsheetHandle = {
+    /** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
+    resizeRow: (row: number, heightPx: number) => void;
+    /** Column-width resize (§6.9-8). / 列幅変更。 */
+    resizeColumn: (col: number, widthPx: number) => void;
+    /**
+     * Programmatic viewport jump to a cell (delegates to the engine's scrollToCell — the
+     * floor-and-pin jump API). Selection is unchanged; the deep grid stays reachable at any
+     * scale (10^9 px). No-op when the grid is unmounted; an out-of-range coordinate is clamped
+     * to the grid edge by the engine (a frozen-axis target is a no-op on that axis).
+     * セルへの命令的 viewport ジャンプ (エンジン scrollToCell へ委譲 — floor + アンカー張りの
+     * ジャンプ API)。選択は不変で、どの尺度 (10^9 px) でも深部到達性を保つ。グリッド未マウント時は
+     * no-op、軸域外の座標はエンジンがグリッド端へクランプ (凍結軸狙いは当該軸で no-op)。
+     */
+    scrollToCell: (cell: CellCoord, options?: ScrollToCellOptions) => void;
+    /** Focuses the sink (`preventScroll` honoured) and re-arms the idle waiting protocol when no session is open (v0.8 §1.10). / シンクへフォーカス (preventScroll 尊重) + 非編集なら再武装 (v0.8 §1.10)。 */
+    focus: (options?: {
+        preventScroll?: boolean;
+    }) => void;
+    /** Runs a command exactly as its chord would (v0.8 §1.10); false = unavailable / gate or adapter rejection / commit-gate refusal. / コマンドをチョードと同じ経路で実行 (false = 不可 / 拒否)。 */
+    executeCommand: (command: SpreadsheetCommand) => boolean;
+    /** Applies a format patch to every selected cell (source "format"); RangeError when getCellFormat is undeclared. / 選択全レンジへ書式パッチ (source "format")。getCellFormat 未宣言は RangeError。 */
+    applyFormat: (patch: CellFormatPatch) => boolean;
+    /** Border preset over the selection (default border thin / BORDER_DEFAULT_COLOR). / 選択への罫線プリセット。 */
+    setBorders: (preset: BorderPreset, border?: CellBorder) => boolean;
+    /** Writes the ACTIVE cell's hyperlink (normalised; null clears; source "annotate"). / active セルのリンク書込 (正規化、null で消去)。 */
+    setHyperlink: (url: string | null) => boolean;
+    /** Writes the ACTIVE cell's note (null clears; source "annotate"). / active セルのノート書込。 */
+    setNote: (text: string | null) => boolean;
+    /** Appends a comment to the ACTIVE cell's thread (existing ids kept + the id-less input, one `comments` patch). / active セルのスレッドへ 1 件追加 (既存 id 保持)。 */
+    addComment: (input: CellCommentInput) => boolean;
+    /** Sets (or clears) the validation rule of every selected cell (source "annotate"). / 選択全セルの検証規則の設定 / 消去。 */
+    setValidation: (rule: DataValidationRule | null) => boolean;
+    /** Menu-path paste (`navigator.clipboard.read`): "applied" = the adapter was called, "empty" = nothing written, "rejected" = refused (always when onClipboardUnavailable fired). / メニュー経路の貼り付け。 */
+    paste: (options: PasteOptions) => Promise<PasteOutcome>;
+    /** The confirmed selection (imperative read). / 確定選択の命令読み。 */
+    getSelection: () => SelectionState;
+    /** The adapter's BASE format of a cell (toolbar state) — the getCellFormat capability branch. / セルの base 書式 (getCellFormat の能力分岐)。 */
+    getBaseFormat: (cell: CellCoord) => CellFormat | undefined;
+    /** base ⊕ conditional formats of a cell (the paint the user sees). / base ⊕ 条件付き書式 (描画される書式)。 */
+    getPaintedFormat: (cell: CellCoord) => CellFormat | undefined;
+    /** Opens the in-place editor on the active cell WITHOUT the virtual-keyboard invitation. / active セルの編集開始 (仮想キーボード招待は上げない)。 */
+    startEdit: (mode: "edit" | "replace") => void;
+    /** Opens a popover on the active cell; RangeError when `popovers[kind] === false` or the capability is undeclared. / active セルへポップオーバーを開く (無効 kind は RangeError)。 */
+    openPopover: (kind: PopoverKind) => void;
+};
+
+/**
+ * The `labels` prop shape: any subset of SpreadsheetLabels (an omitted or `undefined` key keeps
+ * the default). Keys are closed to SpreadsheetLabels.
+ * `labels` prop の形: SpreadsheetLabels の任意の部分集合 (省略 / undefined は既定のまま)。キーは
+ * SpreadsheetLabels に閉じる。
+ */
+export declare type SpreadsheetLabelOverrides = {
+    readonly [K in keyof SpreadsheetLabels]?: SpreadsheetLabels[K];
+};
+
+/**
+ * @fileoverview UI label vocabulary (v0.8 §1.6 / §4.1.17) — the ONE label bag of the package.
+ * The v0.7 `sinkAriaLabel` / `rootAriaLabel` props are folded into it (clean cut-over: no alias
+ * props remain), joined by the popover / indicator strings of the rich-cell UI. Pure, React-free.
+ *
+ * Contract (each clause is pinned by labels.spec.ts):
+ * - `SpreadsheetLabels` is the closed key set; `DEFAULT_LABELS` supplies an English default for
+ *   every key. Count-aware keys are typed `string | ((n: number) => string)`.
+ * - `resolveLabels(overrides)` is the single fold point: a key takes its override when the
+ *   override is not `undefined` and the default otherwise (exactly the destructuring-default
+ *   semantics the two folded props had in v0.7), then `assertLabels` runs on the result.
+ *   `undefined` overrides resolve to `DEFAULT_LABELS` by identity.
+ * - `assertLabels`: `sinkAriaLabel` MUST be a string mentioning "Escape" (WCAG 2.1.2 escape-method
+ *   advisement, spec 00 §10-4) — otherwise a RangeError, thrown at mount by the root.
+ * - `resolveLabel(labels, key, n)` is the single read point: a function-valued label receives `n`
+ *   (omitting `n` for a function value is a RangeError — never a silent 0), a string is returned
+ *   as-is (`n` ignored, so a consumer may override a count key with a plain string).
+ *
+ * UI ラベル語彙 (v0.8 §1.6 / §4.1.17) — パッケージ唯一のラベル集合。v0.7 の `sinkAriaLabel` /
+ * `rootAriaLabel` prop を畳み込み (クリーンカットオーバー: 別名 prop は残さない)、リッチセル UI の
+ * ポップオーバー / インジケータ文言を加える。純関数・React 非依存。
+ * 契約: `SpreadsheetLabels` は閉じたキー集合、`DEFAULT_LABELS` は全キーの英語既定、件数キーは
+ * `string | ((n: number) => string)`。`resolveLabels` が唯一の畳込み点 (undefined でない override を
+ * 採用、それ以外は既定 — 畳み込んだ 2 prop が v0.7 で持っていた分割代入既定と同じ意味論。
+ * override 未指定は `DEFAULT_LABELS` を identity で返却) で、続けて `assertLabels`
+ * (`sinkAriaLabel` は "Escape" を含む文字列であること — spec 00 §10-4、違反はマウント時 RangeError)。
+ * `resolveLabel` が唯一の読み出し点 (関数値は n 必須 — 省略は RangeError、文字列はそのまま)。
+ */
+/**
+ * The closed label vocabulary. Every key has a default in DEFAULT_LABELS; consumers override any
+ * subset through the `labels` prop (SpreadsheetLabelOverrides).
+ * 閉じたラベル語彙。全キーが DEFAULT_LABELS に既定を持ち、消費者は `labels` prop で任意の部分集合を上書き。
+ */
+export declare type SpreadsheetLabels = {
+    /** Accessible name of the sink (grid input receptor); MUST mention "Escape" (spec 00 §10-4). / シンクのアクセシブルネーム ("Escape" 必須)。 */
+    sinkAriaLabel: string;
+    /** Accessible name of the root role="group" landing point. / root 着地点のアクセシブルネーム。 */
+    rootAriaLabel: string;
+    /** Note popover heading. / ノートポップオーバーの見出し。 */
+    noteTitle: string;
+    /** Note popover save button. / ノートの保存ボタン。 */
+    noteSave: string;
+    /** Note popover hint in the normal state (Escape saves and closes). / 通常状態のノートヒント。 */
+    noteEscapeHint: string;
+    /** Note popover hint in the rejected state (Ctrl+Enter retries, Escape closes without saving). / 拒否状態のノートヒント。 */
+    noteRejectedHint: string;
+    /** Comment popover heading. / コメントポップオーバーの見出し。 */
+    commentTitle: string;
+    /** Comment reply field label. / 返信入力欄のラベル。 */
+    commentReply: string;
+    /** Comment post button. / コメント投稿ボタン。 */
+    commentPost: string;
+    /** Comment count text; a function receives the thread length. / コメント件数 (関数はスレッド長を受け取る)。 */
+    commentCount: string | ((n: number) => string);
+    /** Link popover heading. / リンクポップオーバーの見出し。 */
+    linkTitle: string;
+    /** Link popover display-text field label. / リンク表示文字列の入力欄ラベル。 */
+    linkTextField: string;
+    /** Link popover URL field label. / リンク URL の入力欄ラベル。 */
+    linkUrlField: string;
+    /** Link popover open button (only when onHyperlinkOpen is declared). / リンクを開くボタン。 */
+    linkOpen: string;
+    /** Link popover save button. / リンクの保存ボタン。 */
+    linkSave: string;
+    /** Validation-list popover heading. / 検証リストポップオーバーの見出し。 */
+    listTitle: string;
+    /** Validation-list popover text when no option matches. / 候補なしの表示。 */
+    listEmpty: string;
+    /** Validation-list popover overflow row (options beyond the render cap); a function receives the hidden-option count. / 検証リストの上限超過行 (描画上限を超えた候補) — 関数は非表示件数を受け取る。 */
+    listMore: string | ((n: number) => string);
+    /** Message popover heading. / メッセージポップオーバーの見出し。 */
+    messageTitle: string;
+    /** Message shown when a strict validation rule rejects the typed value. / 厳格検証で拒否されたときの文言。 */
+    validationRejected: string;
+    /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
+    popoverClose: string;
+    /** Accessible label of the note indicator on a cell. / ノートインジケータのラベル。 */
+    indicatorNote: string;
+    /** Accessible label of the comment indicator on a cell. / コメントインジケータのラベル。 */
+    indicatorComment: string;
+    /** Accessible label of the invalid-value indicator on a cell. / 無効値インジケータのラベル。 */
+    indicatorInvalid: string;
+};
+
+/**
+ * Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
+ * gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
+ * "paste" / "fill" and, since v0.8, the format commands "format", the self-calculation
+ * commands "calc" and the note / comment / hyperlink / validation writes "annotate"). The write
+ * subset is exactly the non-edit `EditRejection.source` vocabulary (sealed by the type-parity
+ * guard in dataAdapter.spec.ts). Each widening (v0.2 "fill" / "resize", v0.8 the three
+ * command kinds) is a 0.x breaking change for consumers who annotated the callback parameter
+ * with the old inline union — contravariant position.
+ * ADR-12 拒否チャネルの一括操作種別 (公開語彙)。直列化のみのジェスチャ ("copy" / "cut")・
+ * グリッド幾何 ("resize")・**書込**ジェスチャ ("delete" / "paste" / "fill" と、v0.8 からの書式
+ * コマンド "format"・自己計算コマンド "calc"・ノート / コメント / リンク / 検証の書込
+ * "annotate")。書込部分集合は非 edit の `EditRejection.source` 語彙と過不足なく一致
+ * (dataAdapter.spec.ts の型パリティガードが封印)。各拡張 (v0.2 の "fill" / "resize"、v0.8 の
+ * コマンド 3 種) は旧インライン union を明示注釈していた consumer に対する 0.x の破壊枠
+ * (コールバック引数 = 反変位置)。
+ */
+export declare type SpreadsheetOperation = "copy" | "cut" | "delete" | "paste" | "fill" | "resize" | "format" | "calc" | "annotate";
+
+/** Public props (v0.1.0 contract — §6.9). / 公開 props (v0.1.0 契約 — §6.9)。 */
+export declare type SpreadsheetProps = {
+    /**
+     * Identity-stable contract: replacing the adapter object means "sheet switch" and re-slices
+     * every visible cell. Do NOT recreate it per render.
+     * identity 安定契約 — 差し替えは「シート切替」(全再スライス)。毎レンダー生成は禁止。
+     */
+    adapter: SpreadsheetDataAdapter;
+    defaultRowHeight?: number;
+    /** Default column width (also the grid's Fenwick baseValue — behaviorOptions.defaultColWidth §7-8). Per-column widths are set via resizeColumn (the v0.3 initialColumnWidth eager initializer is retired). / 既定列幅 (グリッドの Fenwick baseValue も兼ねる §7-8)。列別幅は resizeColumn で設定 (v0.3 の initialColumnWidth eager 初期化は廃止)。 */
+    defaultColumnWidth?: number;
+    /**
+     * Freezes the first N columns at the left edge (v0.5 — the VirtualGrid frozenLeadingCols
+     * pass-through; LIVE prop). Validation is the engine's fail-fast contract (integer in
+     * [0, 128] — RangeError otherwise; values beyond colCount freeze every column). Frozen
+     * columns stay visible at any horizontal scroll; scrollToCell / keyboard ensure-visible
+     * treat them as always-visible (horizontal no-op). A mid-flight change cancels every
+     * in-flight drag gesture without restore (R2 fix — press-time anchors belong to the OLD
+     * coordinate partition; mixing them with fresh post-change hit tests can commit fill
+     * writes into cells the user never targeted). Selection and the editing session survive.
+     * 先頭 N 列の左端凍結 (v0.5 — VirtualGrid frozenLeadingCols の素通し。ライブ prop)。検証は
+     * エンジンの fail-fast 契約 ([0, 128] 整数、colCount 超過は全列凍結)。凍結列は横スクロール
+     * 位置に依らず常時可視で、scrollToCell / キーボード可視化の横成分は no-op。飛行中の変更は
+     * 全ドラッグジェスチャを復元なしで取り消す (R2 是正 — 押下時アンカーは旧パーティション
+     * 座標系。変更後の鮮度ヒットテストと混ざると狙っていないセルへの fill 確定になる)。選択と
+     * 編集セッションは保持。
+     */
+    frozenColumns?: number;
+    /**
+     * Freezes the first N rows at the top (v0.6 — the VirtualGrid frozenLeadingRows pass-through;
+     * LIVE prop). Same engine fail-fast contract ([0, 128] integer; > rowCount freezes all).
+     * Frozen rows stay visible at any vertical scroll; scrollToCell / ensure-visible treat them
+     * as always-visible (vertical no-op). A mid-flight change cancels every in-flight drag.
+     * 先頭 N 行の上端凍結 (v0.6 — VirtualGrid frozenLeadingRows の素通し。ライブ prop)。エンジンの
+     * fail-fast 契約 ([0, 128] 整数、rowCount 超過は全行凍結) は列と同文。凍結行は縦スクロール
+     * 位置に依らず常時可視で、可視化の縦成分は no-op。飛行中の変更は全ドラッグを取り消す。
+     */
+    frozenRows?: number;
+    /**
+     * Identity-stable contract (same as adapter): an inline arrow here defeats the CellView memo
+     * and turns every host re-render into a full visible re-slice (~800 cells at 16k columns).
+     * identity 安定契約 — インライン関数は memo を無効化し毎レンダー全再スライスになる。
+     */
+    renderCell?: (ctx: RenderCellContext) => ReactNode;
+    /**
+     * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
+     * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
+     * with ONE documented in-drag firing point: the header subtract reservation converts to a
+     * real press on the first movement, firing the deferred press replace mid-drag (total fire
+     * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. Independent
+     * of the live region's 200ms debounce (firing point: the §6.9-1 setSelection wrapper).
+     * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
+     * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
+     * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。
+     */
+    onSelectionChange?: (selection: SelectionState) => void;
+    /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
+    onCellContextMenu?: (cell: CellCoord, origin: {
+        kind: "pointer";
+        event: MouseEvent;
+    } | {
+        kind: "keyboard";
+        cellRect: {
+            top: number;
+            left: number;
+            width: number;
+            height: number;
+        };
+    }) => void;
+    /** Undo request relay (history lives in the consumer — ADR-6). / Undo 要求の中継。 */
+    onUndoRequest?: () => void;
+    /** Redo request relay. / Redo 要求の中継。 */
+    onRedoRequest?: () => void;
+    /** Multi-range copy notice: copy/cut acts on the tail range only and fires this (documented deviation — Excel rejects non-aligned multi-range copy; aligned concat-copy is unsupported). / 複数レンジコピー通知 (末尾レンジのみ実行 + 通知の明示逸脱)。 */
+    onCopyMultiRange?: () => void;
+    /** Rejection notice with reason: "limit" = maxOperationCells exceeded (ADR-12; resize row fan-out gates at maxOperationCells / 10 and autofit at / 4 — §13 design returns), "bounds" = cut-move clipped at the grid edge (§6.5.4-4) OR a row resize that would push the axis-wide hidden-row total past 1,000 (§5.4(b)). 3-arg from v0.1.0 (adding later is breaking). / 拒否理由つき通知 ("bounds" は cut-move の格子端クリップと行非表示軸総数ゲートの 2 系統)。 */
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void;
+    /**
+     * Edit rejection notice — fires once per rejected applyEdits with the thrown error and the
+     * {@link EditRejection} context: which write path was refused (edit / paste / fill / delete —
+     * a cut-move is the Ctrl+V gesture and reports "paste", the same name onOperationRejected
+     * uses for it) and, for an in-cell commit, whether the editing session is KEPT (in-grid commit —
+     * it stays open with the typed value and focus; Escape cancels, or the value can be fixed)
+     * or DISCARDED (grid-exit focusout — the grid closes it as this rejection completes: once
+     * the callback returns the typed value is gone and the sink re-armed WITHOUT moving focus,
+     * which stays wherever the focusout left it — on the element the user chose, or still on the
+     * hidden input after a window blur). Consumers should word their notice from that context; telling the user to
+     * "press Escape" after a discarded session is wrong (an idle Escape hands focus out of the
+     * grid — WCAG 2.1.2).
+     * 編集拒否通知 — 拒否された applyEdits ごとに 1 回、throw されたエラーと
+     * {@link EditRejection} 文脈 (拒否経路 edit / paste / fill / delete — cut-move は Ctrl+V の
+     * ジェスチャで onOperationRejected と同じ "paste" — と、セル内確定なら
+     * セッションが**維持** (グリッド内確定 — 入力値とフォーカスごと開いたまま。Escape で取消 /
+     * 修正可) か**破棄** (グリッド外 focusout — この拒否の完了と同時にグリッドが閉じる:
+     * コールバックが返った時点で入力値は消え、シンクはフォーカスを動かさずに再武装 — フォーカスは
+     * focusout が残した場所 (ユーザーが選んだ要素、ウィンドウ blur なら隠し入力のまま) にある) か)
+     * を届ける。消費者は文脈に沿って文言を組む — 破棄済みで「Escape を押せ」は誤案内 (待機中の
+     * Escape は WCAG 2.1.2 のフォーカス脱出)。
+     */
+    onEditRejected?: (error: unknown, rejection: EditRejection) => void;
+    /** Change notice for out-of-package writes (undo / collaboration); each increment repaints visible cells (§6.9-2). / パッケージ外経路のデータ変更通知。 */
+    dataVersion?: number;
+    /** Operation cell-count ceiling, default 100,000 (ADR-12). / 操作セル数上限。 */
+    maxOperationCells?: number;
+    /**
+     * §11 opt-out (default true): false suppresses the fill-handle node AND inerts its
+     * machine. Fill is a WRITE operation (applyEdits) — read-only adapters opt out to avoid
+     * the onEditRejected UX on every fill attempt.
+     * §11 の opt-out (既定 true)。false はハンドルノードごと非表示 + 機械不活性。fill は書込系
+     * (applyEdits) — 読み取り専用 adapter は毎回の onEditRejected UX を避けるため false にする。
+     */
+    enableFillHandle?: boolean;
+    /**
+     * §11 opt-out (default true): false suppresses the resize strip / unhide marker DOM
+     * entirely (track children, not resident nodes) and inerts the band listeners. NOTE:
+     * false also removes the unhide markers — a consumer with hidden tracks loses the
+     * in-package restore affordance (imperative resize API only).
+     * §11 の opt-out (既定 true)。false はストリップ / マーカーの DOM 生成ごと抑止 + 帯リスナー
+     * 不活性。注意: unhide マーカーも消える — 非表示トラックを持つ consumer はパッケージ内の
+     * 復元手段を失う (命令 API のみ)。
+     */
+    enableResizeUI?: boolean;
+    /**
+     * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
+     * is the RAW canonical getCellText; `displayText` is what a sighted user sees (the
+     * getCellFormat-formatted string — equals `text` when the cell has no format), so AT can
+     * hear "87.0%" for a cell whose raw value is "0.87".
+     * AT 向け読み上げ文言 (省略で無音)。`text` は素の正準 getCellText、`displayText` は目視と同じ
+     * 表示文字列 (getCellFormat 整形後 — 書式なしセルでは text と同値)。素値 "0.87" の表示
+     * "87.0%" をそのまま読み上げられる。
+     */
+    formatCellAnnouncement?: (ctx: {
+        row: number;
+        col: number;
+        text: string;
+        displayText: string;
+        columnName: string;
+    }) => string;
+    /** AT announcement for the selection extent ("A1 to C3, 3 rows 3 cols"); omit for silence. / AT 向け選択範囲読み上げ。 */
+    formatSelectionAnnouncement?: (ctx: {
+        range: CellRange;
+        anchor: CellCoord;
+        active: CellCoord;
+        rangeRowCount: number;
+        rangeColCount: number;
+        rangeCount: number;
+    }) => string;
+    /**
+     * Opt-in AT feedback for commands (v0.8 §1.9): `state` is the toggle's post-state, `null`
+     * for non-toggle commands; the text goes to the live region like the other announcements.
+     * コマンドの AT 通知 (opt-in、v0.8 §1.9)。`state` はトグル後状態 (非トグルは null)。live region へ。
+     */
+    formatCommandAnnouncement?: (ctx: {
+        command: SpreadsheetCommand;
+        state: boolean | null;
+    }) => string;
+    /**
+     * UI label vocabulary (v0.8 §1.6) — folds the former `sinkAriaLabel` / `rootAriaLabel` props
+     * (clean cut-over). An omitted or explicitly `undefined` key keeps the English default. The
+     * resolved `sinkAriaLabel` MUST mention "Escape" (WCAG 2.1.2 escape advisement, §10-4) — a
+     * RangeError is thrown during render otherwise.
+     * UI ラベル語彙 (v0.8 §1.6) — 旧 sinkAriaLabel / rootAriaLabel prop を畳込み (クリーンカットオーバー)。
+     * 省略 / 明示 undefined は英語既定。解決後の sinkAriaLabel は "Escape" を含むこと (違反は render 中
+     * RangeError — §10-4)。
+     */
+    labels?: SpreadsheetLabelOverrides;
+    /**
+     * Rebindable command chords (v0.8 §1.9 / ADR-17): an array REPLACES that command's default
+     * list, `null` unbinds it. Validated at prop time — a non-canonical chord, a modifier-less
+     * chord, a single string, an override of a non-rebindable row (`pasteSpecial`), a clash with
+     * a non-rebindable built-in row in the command's column, or one chord bound to two commands
+     * throws a RangeError during render (`clampZoom` precedent). Consulted through a ref.
+     * 再バインド可能なコマンドチョード (v0.8 §1.9 / ADR-17)。配列は既定一覧の置換、null は未束縛。
+     * prop 時検証 (非正準 / 修飾なし / 単一 string / 非再バインド行の上書き / 列内予約行との一致 /
+     * 二重束縛は render 中 RangeError)。ref 経由で参照。
+     */
+    shortcuts?: ShortcutOverrides;
+    /**
+     * Custom colour slots for `fillColorCustom1..5` / `fontColorCustom1..5`: each axis is exactly
+     * 5 `#rrggbb` strings (a different length or a non-hex entry throws a RangeError at prop
+     * time); an omitted axis uses DEFAULT_CUSTOM_COLORS.
+     * 塗り / 文字色のカスタム 5 スロット (各軸ちょうど 5 本の `#rrggbb` — 本数違い / 非 hex は prop 時
+     * RangeError。省略軸は DEFAULT_CUSTOM_COLORS)。
+     */
+    colors?: {
+        readonly fill?: readonly string[];
+        readonly font?: readonly string[];
+    };
+    /**
+     * Host currency / locale for `formatCurrency` and for bare currency symbols in pasted HTML;
+     * undeclared ⇒ the `formatCurrency` row passes through and bare symbols are not recovered.
+     * `formatCurrency` と貼り付け HTML の裸通貨記号復元に使う通貨 / locale。未宣言なら `formatCurrency`
+     * 行は素通しで、裸記号は復元しない。
+     */
+    formats?: {
+        readonly currency: string;
+        readonly locale?: string;
+    };
+    /**
+     * Highlight bands of the selection (v0.8 §2.4): controlled value — the same two-phase
+     * contract as `zoom`. Default (both props omitted) is all off ⇒ zero band nodes (v0.7 DOM
+     * identity). Repainted imperatively on change.
+     * 選択の強調帯 (v0.8 §2.4) の制御値 (zoom と同型の二相契約)。両 prop 省略時は全 off = 帯ノード 0
+     * (v0.7 DOM 恒等)。変更は命令再描画。
+     */
+    highlight?: HighlightState;
+    /** Initial highlight state for the uncontrolled mode. / 非制御モードの初期強調状態。 */
+    defaultHighlight?: HighlightState;
+    /** Fires when a highlight toggle command requests a new state (a controlled consumer applies it). / 強調トグルコマンドの変更要求通知 (制御 consumer が反映)。 */
+    onHighlightChange?: (highlight: HighlightState) => void;
+    /**
+     * Band colours + opacity — identity-stable; written to `--aqsp-band-row / -column /
+     * -intersection / -opacity` on the overlay in a layout effect. Each colour must parse
+     * (`normalizeColor`) and `opacity` must be a finite number in [0, 1] — RangeError at prop time
+     * otherwise. Undeclared ⇒ nothing is written while every band is off (the overlay's style
+     * attribute stays byte-identical to v0.7) and DEFAULT_HIGHLIGHT_COLORS (`#0084FF` / `#42FF4F` /
+     * `#E1FF00` / 0.2) is written once a band turns on.
+     * 帯の色 3 種 + 不透明度 (identity 安定、layout effect で `--aqsp-band-*` へ)。解釈不能な色 /
+     * [0, 1] 外の不透明度は prop 時 RangeError。未宣言なら全 off の間は何も書かず (overlay の style は
+     * v0.7 と byte 同一)、帯が on になった時点で DEFAULT_HIGHLIGHT_COLORS を書く。
+     */
+    highlightColors?: HighlightColors;
+    /** Per-kind popover opt-out (v0.8 §1.8): `false` ⇒ that kind's commands pass through and `openPopover(kind)` throws a RangeError. / kind 別ポップオーバー opt-out (false は素通し + openPopover は RangeError)。 */
+    popovers?: PopoverOverrides;
+    /** Replaces the default popover components (receives the kind-discriminated context). / 既定ポップオーバーの差替え (kind 判別文脈を受ける)。 */
+    renderPopover?: (ctx: PopoverContext) => ReactNode;
+    /** Clip state notice: armed (`foreign: false`), discarded (`null`), or a cut kept across a sheet switch (`foreign: true`). / クリップ状態通知 (武装 / 破棄 / シート切替を跨いだ cut は foreign)。 */
+    onClipChange?: (clip: ClipInfo | null) => void;
+    /** Hyperlink navigation seam (Alt+Enter, the link popover's Open button, and Ctrl / Meta+click on a link cell — spec 08 §11 D-53) — undeclared ⇒ no navigation, no Open button, no pointer gesture. / ハイパーリンク遷移シーム (Alt+Enter / Open ボタン / リンクセルへの Ctrl / Meta+クリック — 分冊 08 §11 D-53)。未宣言 = 遷移なし・Open ボタンなし・ポインタジェスチャなし。 */
+    onHyperlinkOpen?: (url: string, cell: CellCoord) => void;
+    /** Strict validation rejection notice (v0.8 §1.9) — the commit never reaches the adapter; the message popover shows the rejection. / strict 検証拒否の通知 (commit はアダプタへ届かず、message ポップオーバーが拒否を示す)。 */
+    onValidationRejected?: (ctx: {
+        cell: CellCoord;
+        rule: DataValidationRule;
+        text: string;
+        message: string;
+    }) => void;
+    /** Ctrl+Alt+V request with the active cell's viewport rect (visual px, keyboard-origin shape of onCellContextMenu); undeclared ⇒ `paste({ mode: "formats" })`. / Ctrl+Alt+V の要求通知 (未宣言なら書式のみ貼り付け)。 */
+    onPasteSpecialRequest?: (origin: {
+        kind: "keyboard";
+        cellRect: {
+            top: number;
+            left: number;
+            width: number;
+            height: number;
+        };
+    }) => void;
+    /** Menu-path clipboard refusal channel; whenever it fires `paste()` resolves "rejected". / メニュー経路の拒否通知 (発火時 `paste()` は必ず "rejected")。 */
+    onClipboardUnavailable?: (cause: "insecure-origin" | "permission-denied" | "empty" | "unreadable") => void;
+    /** Clock seam for `insertDate` / `insertTime` (declared default: Date.now). / insertDate / insertTime の時計シーム (宣言済み既定 Date.now)。 */
+    now?: () => number;
+    /**
+     * Package-level zoom (v0.3): controlled value, clamped to [0.25, 4]. The grid scales
+     * visually (transform) while ALL logic stays in logical px; both scrollbars compensate
+     * ancestor scale natively. Omit for the uncontrolled mode (defaultZoom + gestures).
+     * パッケージズーム (v0.3)。制御値 ([0.25, 4] clamp)。視覚は transform スケール、論理は
+     * 論理 px のまま (両スクロールバーは祖先スケール補正内蔵)。省略時は非制御 (defaultZoom +
+     * ジェスチャ)。
+     */
+    zoom?: number;
+    /** Initial zoom for the uncontrolled mode (default 1). / 非制御時の初期ズーム (既定 1)。 */
+    defaultZoom?: number;
+    /**
+     * Fires when a zoom gesture (Alt+Wheel / Ctrl+Alt+= / Ctrl+Alt++ / Ctrl+Alt+- / Ctrl+Alt+0) requests a
+     * new zoom — in the controlled mode the consumer applies it (the gesture alone does not
+     * change the view). All four keys match on the PRODUCED character (event.key) regardless
+     * of Shift, so layouts that need Shift to type them work as-is (JIS `=` = Shift+`-`,
+     * US `+` = Shift+`=`, AZERTY `0` = Shift+`à`); mismatching shifted characters (US `_`, `)`)
+     * pass through. Chords carrying the AltGraph modifier state are never claimed (defense in
+     * depth: evergreen browsers deliver real AltGr characters WITHOUT ctrl+alt, so typing e.g.
+     * Latvian AltGr+F `=` never hits this handler; the guard shields legacy AltGr-emulation
+     * shapes only). Gestures are IGNORED while any drag is in
+     * flight (press-time rect caches would skew); a controlled consumer changing `zoom`
+     * mid-drag inherits that skew. Ctrl+Wheel is deliberately NOT bound (the browser owns it).
+     * ズームジェスチャ (Alt+ホイール / Ctrl+Alt+= / + / − / 0 — 4 キーとも Shift 非依存で生成
+     * 文字 event.key を信頼、AltGraph 修飾状態つきは非請求の多層防御 — 実 AltGr 印字は
+     * 修飾なしで届き本ガード非依存) の変更要求通知 — 制御モードでは
+     * consumer が反映する (ジェスチャ単独では変わらない)。飛行中ドラッグの間は要求を無視
+     * (押下時 rect キャッシュが歪むため。制御 consumer がドラッグ中に zoom prop を変えた場合は
+     * 同じ歪みを負う)。Ctrl+ホイールは意図的に非束縛 (ブラウザ所有)。
+     */
+    onZoomChange?: (zoom: number) => void;
+    testId?: string;
+    className?: string;
+};
+
+/**
+ * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
+ * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。
+ */
+declare type SpreadsheetTestProps = {
+    /** Test-only CellView re-render counter; never passed in production. / テスト専用カウンタ。 */
+    __onCellRender?: ProfilerOnRenderCallback;
+};
+
+/** Case-sensitive needle test on the raw text. / 素の text に対する大文字小文字区別の needle 判定。 */
+export declare type TextCondition = {
+    type: "text";
+    op: CfTextOp;
+    value: string;
+};
+
+/** The code-point length of the text must satisfy `op` against the finite numeric bounds `a` (and `b`). / text のコードポイント数が有限数の境界 a (と b) に対し op を満たす。 */
+export declare type TextLengthValidationRule = {
+    type: "textLength";
+    op: ValidationCompareOp;
+    a: number;
+    b?: number;
+};
+
+/** Substring / shape checks on the text; `value` is the needle for the four needle ops and ignored by isEmail / isUrl. / text の部分文字列 / 形式検査。value は needle 系 4 op の探索文字列で isEmail / isUrl では無視。 */
+export declare type TextValidationRule = {
+    type: "text";
+    op: ValidationTextOp;
+    value?: string;
+};
+
+/**
+ * Converts a formula to R1C1 relative to `origin` (Google Sheets spelling) — the form the clip
+ * payload carries so a paste at any target resolves with {@link fromR1C1}. Non-formula text
+ * and reference-free formulas return the same string instance; an invalid origin is a
+ * RangeError.
+ * 数式を `origin` 基準の R1C1 (Google Sheets 綴り) へ変換 — クリップが運び、任意の貼り付け先で
+ * {@link fromR1C1} が解決する形。非数式・参照なし数式は同一文字列インスタンス、不正な原点は
+ * RangeError。
+ */
+export declare const toR1C1: (formula: string, origin: CellCoord) => string;
+
+/**
+ * Validates committed text against a rule. Blank always passes; `custom` is evaluated only when
+ * the caller passes `evaluate` (commit time — paint omits it); an incomplete rule (unparseable
+ * bound, missing `b` / `value`) is inert; a rule outside the vocabulary throws RangeError.
+ * Message = `rule.errorMessage` when set, else a built-in English summary of the rule.
+ * 確定テキストの規則検証。空文字は常に合格、custom は呼び手が evaluate を渡すとき (確定時 — 描画は
+ * 渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は不活性、語彙外の規則は
+ * RangeError。メッセージは errorMessage があればそれ、無ければ組込みの英語要約。
+ */
+export declare const validateCellText: (rule: DataValidationRule, text: string, evaluate?: ValidationEvaluate) => ValidationVerdict;
+
+/**
+ * @fileoverview Data-validation rule vocabulary and the pure verdict engine (v0.8 — the
+ * getCellValidation capability, ADR-13). The consumer declares a per-cell DataValidationRule
+ * via the optional adapter capability getCellValidation(row, col); the editor asks
+ * validateCellText at COMMIT (passing the adapter's formula evaluator for `custom` rules) and
+ * the grid asks isVisiblyInvalid at PAINT (never evaluating a formula) to draw the invalid
+ * indicator. React-free and total.
+ *
+ * Engine contract (each clause is load-bearing and mutation-gated — spec 01 §8.3):
+ * - BLANK IS ALWAYS VALID: the empty string satisfies every rule (Excel "ignore blank"), so a
+ *   validated cell can always be cleared; `custom` is not even evaluated for a blank.
+ * - EXACT decimal comparison for `number` rules: the cell text and both bounds are parsed with
+ *   the SAME strict-decimal grammar as cellFormat.ts (`[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d{1,4})?`,
+ *   trimmed, no hex / grouping / ±Infinity) and compared as normalised sign / significant-digit /
+ *   point-position triples — never through a binary double — so "9007199254740993" is greater
+ *   than "9007199254740992" and "0.30000000000000004" is not equal to "0.3".
+ * - TIMEZONE-FREE dates for `date` rules: the pure-calendar grammar of cellFormat.ts
+ *   ("YYYY-MM-DD[ T HH:mm[:ss]]" or "/" separated, leap-aware ranges, no Date object), compared
+ *   as (year, month, day, hour, minute, second) tuples; `between` / `notBetween` are inclusive.
+ * - INERT INCOMPLETE RULES: a bound that does not parse (`a` / `b` for number / date, a
+ *   non-finite `a` / `b` for textLength, a missing `b` for between / notBetween, a missing `value`
+ *   for the needle text ops) makes the rule accept everything — a half-written rule never locks a
+ *   cell. Bounds are never swapped: `between 10 and 5` accepts nothing but blank.
+ * - FAIL-FAST on a rule OUTSIDE the vocabulary: an unknown `type` or `op` is a consumer bug and
+ *   throws RangeError regardless of the text (fail-soft would silently disable validation).
+ * - INTERNED list Sets per rule object (WeakMap identity), so the paint-time `list` check is O(1)
+ *   even for a 10k-item list; a fresh rule object interns a fresh Set.
+ * - MESSAGE resolution: `errorMessage` when the consumer set it (an empty string is honoured as
+ *   is), else a built-in English summary of the rule.
+ * - `custom` needs the caller's `evaluate`; without it the rule is not evaluated (verdict ok), and
+ *   truth = `true` or a finite non-zero number (the conditionalFormat customFormula convention).
+ * - Matching is exact (case-sensitive, untrimmed) for `list` / `text` / `checkbox`; textLength
+ *   counts Unicode code points. `isEmail` is the WHATWG valid-e-mail grammar with a mandatory
+ *   dotted domain; `isUrl` is a WHATWG-parsable absolute http(s) URL.
+ *
+ * データ検証の規則語彙と純関数の判定エンジン (v0.8 — getCellValidation 能力、ADR-13)。
+ * consumer が任意能力 getCellValidation(row, col) で規則を宣言し、エディタが確定時に
+ * validateCellText (custom 規則にはアダプタの数式評価器を渡す)、グリッドが描画時に
+ * isVisiblyInvalid (数式は決して評価しない) を呼んで不正インジケータを描く。React 非依存・全域関数。
+ * エンジン契約 (全て変異検証で封印 — spec 01 §8.3): 空文字は常に有効 (Excel の「空白を無視」—
+ * 検証セルは必ず消去できる、custom も評価しない)、number は cellFormat.ts と同じ厳密 10 進文法で
+ * 符号 / 有効数字 / 小数点位置の正規形として正確比較 (double 非経由)、date は Date 非依存の純暦文法を
+ * タプル比較 (between は両端含み)、不完全な規則 (解釈不能な境界・between の b 欠落・needle 欠落) は
+ * 不活性 = 全受理 (書きかけの規則でセルを閉じ込めない、境界の入替もしない)、語彙外の type / op は
+ * consumer バグとして text に依らず RangeError、list の Set は規則 object 毎に WeakMap intern、
+ * メッセージは errorMessage (空文字も尊重) が無ければ組込みの英語要約、custom は evaluate 無しなら
+ * 未評価 (ok)・真 = true か有限非 0 数、照合は完全一致 (大文字小文字区別・trim 無し)、textLength は
+ * コードポイント数、isEmail は WHATWG 文法 + ドット付きドメイン必須、isUrl は WHATWG 絶対 http(s) URL。
+ */
+/** Ordered comparison vocabulary shared by number / textLength / date rules; between / notBetween include both bounds. / number / textLength / date 規則が共有する比較語彙。between / notBetween は両端含み。 */
+export declare type ValidationCompareOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "notBetween";
+
+/** A consumer-side formula evaluator handed to validateCellText for `custom` rules. / custom 規則のために validateCellText へ渡す consumer 側の数式評価器。 */
+export declare type ValidationEvaluate = (formula: string) => string | number | boolean | null;
+
+/** Options shared by every rule: `strict` rejects the commit (else warn only), `inputMessage` shows on the active cell, `errorMessage` replaces the built-in verdict message. / 全規則共通のオプション。strict は確定拒否 (無指定は警告のみ)、inputMessage は active セルの案内、errorMessage は組込みメッセージの置換。 */
+export declare type ValidationRuleBase = {
+    strict?: boolean;
+    inputMessage?: string;
+    errorMessage?: string;
+};
+
+/** Text-rule vocabulary: four needle ops (need `value`) and two shape checks (ignore `value`). / text 規則の語彙。needle 系 4 つ (value 必須) と形式検査 2 つ (value 無視)。 */
+export declare type ValidationTextOp = "contains" | "notContains" | "startsWith" | "endsWith" | "isEmail" | "isUrl";
+
+/** The outcome of validateCellText: ok, or rejected with the resolved message. / validateCellText の結果。ok か、解決済みメッセージ付きの拒否。 */
+export declare type ValidationVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+
+export { }