@aiquants/spreadsheet 0.8.0

package/src/clipboard/pasteSpecial.ts

@@ -0,0 +1,608 @@
+/**
+ * @fileoverview Paste-special engine (v0.8 §1.7 / §4.1.9): the paste options vocabulary, the
+ * mode × aspect table and the pure transforms over a ClipPayload that the paste path composes —
+ * transposition (axes AND formula offsets), the write-gate strip of undeclared aspects, the
+ * per-cell patch per mode (values / formats / formulas / no-borders / widths / validation /
+ * conditional formats / comments) with Excel's arithmetic operations, skip-blanks and the
+ * inject-into-empty option, and the conditional-format range translation per tile. Pure,
+ * React-free and TOTAL fail-soft like cellFormat.ts: a payload the caller hands in is never
+ * mutated, nothing throws on data (a missing cell reads as blank, a dictionary index outside
+ * its dictionary reads as an absent aspect), and every transform returns its INPUT BY IDENTITY
+ * when it changes nothing (a 1×1 transpose without sizes / relative formulas, a strip with every
+ * aspect declared, an empty rule list). Nothing here reads an adapter: the caller supplies the
+ * target's text / format through lazy thunks that are called only when the mode needs them.
+ *
+ * Engine contract (each clause is load-bearing and mutation-gated in pasteSpecial.spec.ts):
+ * - MODE × ASPECT TABLE: `MODE_ASPECTS[mode]` lists which aspects a mode writes — `text`,
+ *   `formula` (formulas resolved from the R1C1 form; off ⇒ the value text `t` is written),
+ *   `format`, `borders` (only meaningful with `format`; off = "all except borders"), `cf`,
+ *   `note`, `comments`, `hyperlink`, `validation`, `sizes` (column widths / row heights the
+ *   payload carries when the copy was whole columns / rows). `all` and `noBorders` carry every
+ *   cell aspect + CF + sizes; `formats` = format + borders + CF; `values` / `formulas` = text
+ *   only (`formulas` resolves formulas, `values` never does); `columnWidths` = sizes only;
+ *   `validation` / `conditionalFormats` / `commentsAndNotes` = that aspect only.
+ * - WRITE GATE ("what cannot be read cannot be written"): `stripUndeclaredAspects` removes every
+ *   undeclared aspect from the payload BEFORE tiling (`f` without getCellFormula, `fmt` + the
+ *   `formats` dictionary without getCellFormat, `val` + `validations`, `note`, `comments`,
+ *   `link`, `conditionalFormats`), keeping every untouched cell / row / dictionary by identity;
+ *   `patchFromClipCell` additionally gates each aspect on the same capabilities, so a v0.7
+ *   adapter (no capabilities) receives exactly `{ text }` patches — the v0.7 identity.
+ * - PATCH PER CELL: under a mode that carries an aspect, a source cell WITHOUT that aspect
+ *   writes `null` (clear the target — Excel's "All" / "Formats" / "Validation" replace the
+ *   destination aspect); `format` is the canonical form of the dictionary entry, computed ONCE
+ *   per dictionary index and shared by identity across every cell that references it; under
+ *   `noBorders` the source borders are dropped and the target's EXISTING borders are kept (the
+ *   only read of the target's format); `comments` travel id-less (every pasted comment is new).
+ *   A patch without any key is `null` (the cell is not written).
+ * - SKIP BLANKS: the only per-cell skip. A blank source cell (`t === ""` and no `f`; formatting,
+ *   notes, validation do not count — Excel checks contents only) leaves the target untouched in
+ *   every mode, before any other rule. A formula returning "" is not blank.
+ * - OPERATIONS (Excel Paste Special add / subtract / multiply / divide; the copied value is the
+ *   right operand): applied to the text aspect only, the target text being the target's EDIT
+ *   text (its formula when it holds one). A non-numeric target text is skipped (null); a blank
+ *   target is 0; numeric text is coerced through parseNumber's strict decimal grammar; a numeric
+ *   result is written with 15 significant digits (no binary artefacts: 0.1 + 0.2 ⇒ "0.3"), never
+ *   "-0", and a non-finite result leaves the target. A formula SOURCE is resolved at the target
+ *   (`fromR1C1`) and becomes the right operand of a formula: `=(target)op(operand)` — the target
+ *   side is its formula body, its number, or 0 when blank. A formula TARGET is wrapped the same
+ *   way with a numeric source: `=(SUM(A1:A3))/(2)`. Division by a numeric zero source leaves the
+ *   target (formula sources cannot be tested and are wrapped). A BLANK source counts as 0 under
+ *   add / subtract — the numeric target text is re-entered as a number (Excel's text-to-number
+ *   trick), a formula or blank target is left alone — and leaves the target under multiply /
+ *   divide. A non-numeric source text (incl. TRUE / FALSE) leaves the target. Under a mode
+ *   without `formula` (values) the source's formula is invisible: its value text is the operand.
+ * - INJECT INTO EMPTY: with `injectIntoEmpty`, a mode that does not carry `format` still writes
+ *   the source's canonical format into a target whose text is "" (the sheets-enhancer paste
+ *   setting generalised to the whole format); nothing is written when the source has no format.
+ * - TRANSPOSE: `transposePayload` swaps rows / cols and cell (r, c) ↦ (c, r); every RELATIVE
+ *   reference of a formula is rotated with the geometry (`R[a]C[b]` ⇒ `R[b]C[a]`, a relative
+ *   whole column becomes a relative whole row and vice versa, ranges end-wise), while any
+ *   reference with an absolute axis is left in place (Excel: "use absolute references to keep
+ *   them fixed"; a mixed reference cannot rotate without moving its anchor). Conditional-format
+ *   ranges swap axes. Sizes are axis-bound and do not transpose: the result carries no
+ *   `colWidths` / `rowHeights` and `wholeRows` / `wholeCols` are false. Dictionaries and the
+ *   `clipId` are kept by identity; the caller then tiles the transposed payload normally
+ *   (Sheets-style deviation — Excel refuses a transposed tile). The declared `rows × cols` is the
+ *   shape of truth: a ragged row reads missing cells as blank and drops surplus cells.
+ * - CF TRANSLATION: `translateConditionalFormats` moves every origin-relative range of every rule
+ *   by every tile origin and merges them into ONE input per source rule (rule order kept,
+ *   `stopIfTrue` only when present); ranges are not clipped to the grid (a tile entered at the
+ *   grid edge may extend past it — the consumer clamps, as it does for its own rules).
+ *
+ * 貼り付けスペシャルエンジン (v0.8 §1.7 / §4.1.9): 貼り付けオプション語彙、モード × 側面表、
+ * 貼り付け経路が合成する ClipPayload 上の純変換 — 転置 (軸と数式オフセット)、未宣言側面の書込
+ * ゲート除去、モード別のセル単位パッチ (値 / 書式 / 数式 / 罫線なし / 幅 / 検証 / 条件付き書式 /
+ * コメント) と Excel の演算・空白スキップ・空セル注入、条件付き書式レンジのタイル毎平行移動。
+ * cellFormat.ts と同じく純関数・React 非依存・全域 fail-soft: 渡された payload は変更せず、
+ * データで throw せず (欠けたセルは空白、辞書外索引は側面不在)、無変化の変換は入力を identity で
+ * 返す。アダプタは読まない — ターゲットの text / format は呼び出し側の遅延 thunk で受け取り、
+ * モードが必要とするときだけ呼ぶ。
+ * 契約: モード × 側面表 (`formula` off = 値文字列 `t`、`borders` off = 罫線を除く全て)、書込
+ * ゲート (`stripUndeclaredAspects` は未宣言側面を tiling 前に除去し、`patchFromClipCell` も
+ * 同じ能力で側面毎に門番 — v0.7 アダプタは `{ text }` だけ = v0.7 恒等)、セル毎パッチ (運ぶ
+ * 側面をソースが持たなければ `null` で消去、format は辞書索引毎に 1 回だけ正準化し identity 共有、
+ * `noBorders` はソース罫線を落としターゲット既存罫線を保つ、空パッチは `null`)、空白スキップ
+ * (唯一のセル単位スキップ、内容だけで判定)、演算 (非数ターゲットは skip、空 = 0、15 有効桁、
+ * -0 なし、非有限は不変、数式ソース / 数式ターゲットは `=(左)演算子(右)` へラップ、数値 0 除算は
+ * 不変、空ソースは + − で数として再入力 / × ÷ で不変、非数ソースは不変、values では数式は不可視)、
+ * 空セル注入、転置 (相対参照だけ回転、絶対軸を持つ参照は据え置き、CF レンジは軸交換、寸法は
+ * 運ばない、宣言形状が真実で欠けは空白・余剰は捨てる)、CF 平行移動 (規則毎に 1 入力へ統合、
+ * グリッドへの切り詰めはしない)。
+ */
+
+import type { CellCoord } from "../model/cellCoord.ts"
+import { type CellFormat, canonicalizeFormat, parseNumber } from "../model/cellFormat.ts"
+import type { ConditionalFormatRuleInput } from "../model/conditionalFormat.ts"
+import type { AspectCapabilities, CellPatch } from "../model/dataAdapter.ts"
+import { createFormulaMemo, formatReference, fromR1C1, type ReferenceToken, tokenizeFormula, toR1C1 } from "../model/formulaRefs.ts"
+import type { ClipCell, ClipPayload } from "./clipPayload.ts"
+
+/** The paste-special modes (Excel Paste Special ∪ Sheets Paste special, §1.7). / 貼り付けスペシャルのモード (§1.7)。 */
+export 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 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 type PasteOptions = { mode: PasteMode; operation?: PasteOperation; skipBlanks?: boolean; transpose?: boolean; injectIntoEmpty?: boolean }
+
+/**
+ * The aspects one mode writes (one row of `MODE_ASPECTS`). `formula` is only meaningful with
+ * `text`, `borders` only with `format`.
+ * 1 モードが書く側面 (`MODE_ASPECTS` の 1 行)。`formula` は `text` と、`borders` は `format` と
+ * 組でだけ意味を持つ。
+ */
+export type PasteAspects = {
+    readonly text: boolean
+    readonly formula: boolean
+    readonly format: boolean
+    readonly borders: boolean
+    readonly cf: boolean
+    readonly note: boolean
+    readonly comments: boolean
+    readonly hyperlink: boolean
+    readonly validation: boolean
+    readonly sizes: boolean
+}
+
+/** The modes in §1.7 declaration order (census / menu order); its element type is the literal tuple so the spec can parity-guard it against `PasteMode`. / §1.7 の宣言順のモード一覧 (census / メニュー順)。要素型はリテラルタプルで、spec が `PasteMode` とのパリティを守る。 */
+export const PASTE_MODES = Object.freeze(["all", "values", "formats", "formulas", "noBorders", "columnWidths", "validation", "conditionalFormats", "commentsAndNotes"] as const) satisfies readonly PasteMode[]
+
+/** Builds one frozen aspect row from the aspects that are ON. / ON の側面から凍結した 1 行を組む。 */
+const aspectRow = (on: readonly (keyof PasteAspects)[]): PasteAspects =>
+    Object.freeze({
+        text: on.includes("text"),
+        formula: on.includes("formula"),
+        format: on.includes("format"),
+        borders: on.includes("borders"),
+        cf: on.includes("cf"),
+        note: on.includes("note"),
+        comments: on.includes("comments"),
+        hyperlink: on.includes("hyperlink"),
+        validation: on.includes("validation"),
+        sizes: on.includes("sizes"),
+    })
+
+/** Every aspect — the `all` row. / 全側面 — `all` 行。 */
+const EVERY_ASPECT: readonly (keyof PasteAspects)[] = ["text", "formula", "format", "borders", "cf", "note", "comments", "hyperlink", "validation", "sizes"]
+
+/**
+ * The mode × aspect table (the spec 08 table, enumerable for the census test). Frozen at both
+ * levels.
+ * モード × 側面表 (spec 08 の表、census テストが列挙する)。両階層とも凍結。
+ */
+export const MODE_ASPECTS: { readonly [M in PasteMode]: PasteAspects } = Object.freeze({
+    all: aspectRow(EVERY_ASPECT),
+    values: aspectRow(["text"]),
+    formats: aspectRow(["format", "borders", "cf"]),
+    formulas: aspectRow(["text", "formula"]),
+    noBorders: aspectRow(EVERY_ASPECT.filter((aspect) => aspect !== "borders")),
+    columnWidths: aspectRow(["sizes"]),
+    validation: aspectRow(["validation"]),
+    conditionalFormats: aspectRow(["cf"]),
+    commentsAndNotes: aspectRow(["note", "comments"]),
+})
+
+/** The options of a plain Ctrl+V — mode `all`, nothing else. / 素の Ctrl+V のオプション — `all` のみ。 */
+export const DEFAULT_PASTE_OPTIONS: PasteOptions = Object.freeze({ mode: "all" })
+
+/**
+ * One target cell as `patchFromClipCell` sees it: its coordinate (the formula resolution
+ * origin) and two lazy reads the engine calls only when the mode needs them — `readText`
+ * (edit text: the formula when the cell holds one) for operations and inject-into-empty,
+ * `readFormat` (base format) under `noBorders` only.
+ * `patchFromClipCell` が見るターゲットセル: 座標 (数式解決の原点) と、モードが必要とするときだけ
+ * 呼ばれる 2 つの遅延読み — `readText` (編集文字列: 数式があれば数式) は演算と空セル注入、
+ * `readFormat` (base 書式) は `noBorders` だけが呼ぶ。
+ */
+export type PasteTarget = { readonly row: number; readonly col: number; readonly readText: () => string; readonly readFormat: () => CellFormat | undefined }
+
+/** The shared blank cell a ragged payload reads for a missing position. / 欠けた位置に読む共有の空白セル。 */
+const BLANK_CELL: ClipCell = Object.freeze({ t: "" })
+
+/**
+ * The transposition pivot: both axes share it so rotating a relative offset about it is a plain
+ * row ↔ column swap, far enough from 0 that no real offset resolves below the grid.
+ * 転置の支点: 両軸で同じ値なので相対差分の回転は行 ↔ 列の単純交換になり、実在し得る差分が 0
+ * 未満へ落ちない距離にある。
+ */
+const TRANSPOSE_PIVOT: CellCoord = Object.freeze({ row: 1 << 30, col: 1 << 30 })
+
+/** Operator text per operation. / 演算毎の演算子文字。 */
+const OPERATOR_TEXT: { readonly [O in PasteOperation]: string } = Object.freeze({ add: "+", subtract: "-", multiply: "*", divide: "/" })
+
+/** Blank = no contents: empty text and no formula (formatting / notes do not count). / 空白 = 内容なし: 空文字かつ数式なし (書式 / ノートは数えない)。 */
+export const isBlankCell = (cell: ClipCell): boolean => cell.t === "" && cell.f === undefined
+
+/** Whether an edit text is a formula (a lone "=" is text). / 編集文字列が数式か (単独の "=" は文字列)。 */
+const isFormulaText = (text: string): boolean => text.length > 1 && text.startsWith("=")
+
+/** IEEE arithmetic for one operation. / 1 演算の IEEE 算術。 */
+const compute = (left: number, right: number, operation: PasteOperation): number => {
+    switch (operation) {
+        case "add":
+            return left + right
+        case "subtract":
+            return left - right
+        case "multiply":
+            return left * right
+        case "divide":
+            return left / right
+    }
+}
+
+/**
+ * Cell text for a numeric result: 15 significant digits (Excel's display precision — hides
+ * binary artefacts), never "-0"; null when not finite.
+ * 数値結果のセル文字列: 15 有効桁 (Excel の表示精度 — 2 進誤差を隠す)、"-0" は出さない、非有限は null。
+ */
+const resultText = (value: number): string | null => {
+    if (!Number.isFinite(value)) {
+        return null
+    }
+    // toPrecision(15) で丸め、Number で末尾 0 / 指数表記を正規化 (String(-0) は "0")
+    return String(Number(value.toPrecision(15)))
+}
+
+/**
+ * Excel Paste Special arithmetic on one target (rules in the fileoverview): returns the new
+ * cell text, or null to leave the target untouched. `targetText` is the target's EDIT text
+ * (its formula when it holds one); `target` resolves a formula source's R1C1 form.
+ * Excel の演算をターゲット 1 セルへ適用 (規則は fileoverview): 新しいセル文字列、または触らない
+ * null。`targetText` はターゲットの編集文字列 (数式があれば数式)、`target` は数式ソースの R1C1 を
+ * 解決する座標。
+ */
+export const applyOperation = (targetText: string, source: ClipCell, operation: PasteOperation, target: CellCoord): string | null => {
+    // ターゲットの分類: 数式 / 数値 (空は 0) / それ以外は触らない
+    const targetIsFormula = isFormulaText(targetText)
+    const targetNumber = targetText === "" ? "0" : parseNumber(targetText)
+    if (!targetIsFormula && targetNumber === null) {
+        return null
+    }
+    const operator = OPERATOR_TEXT[operation]
+    // 数式ソース: ターゲットで解決した数式を右オペランドにしてラップ (0 除算は判定不能)
+    if (source.f !== undefined) {
+        const operand = fromR1C1(source.f, target)
+        const right = operand.startsWith("=") ? operand.slice(1) : operand
+        const left = targetIsFormula ? targetText.slice(1) : targetNumber
+        return `=(${left})${operator}(${right})`
+    }
+    // 空ソース: + − は 0 (数値テキストを数として再入力、数式 / 空ターゲットは不変)、× ÷ は不変
+    if (source.t === "") {
+        if (operation === "multiply" || operation === "divide" || targetIsFormula || targetText === "") {
+            return null
+        }
+        return resultText(Number(targetNumber))
+    }
+    // 非数のソース文字列は触らない
+    const sourceNumber = parseNumber(source.t)
+    if (sourceNumber === null) {
+        return null
+    }
+    const right = Number(sourceNumber)
+    // 数値 0 で割る貼り付けはターゲット不変
+    if (operation === "divide" && right === 0) {
+        return null
+    }
+    // 数式ターゲットは数値ソースをそのまま右オペランドにしてラップ
+    if (targetIsFormula) {
+        return `=(${targetText.slice(1)})${operator}(${sourceNumber})`
+    }
+    return resultText(compute(Number(targetNumber), right, operation))
+}
+
+/** A swapped cell end (relative both ways — the caller checks). / 両端交換したセル端 (相対同士 — 判定は呼び出し側)。 */
+const swapCellEnd = (end: { row: number; col: number; absRow: boolean; absCol: boolean }): { row: number; col: number; absRow: boolean; absCol: boolean } => ({ row: end.col, col: end.row, absRow: false, absCol: false })
+
+/**
+ * Rotates one A1 token about the shared pivot: fully relative references swap row ↔ column
+ * (cell, both range ends, whole column ↔ whole row); any absolute axis pins the token in place.
+ * Returns the input token by identity when unchanged.
+ * A1 トークン 1 つを共有支点で回転: 完全相対の参照は行 ↔ 列を交換 (セル、レンジ両端、全列 ↔ 全行)、
+ * 絶対軸が 1 つでもあれば据え置き。無変化は入力トークンを identity で返す。
+ */
+const rotateToken = (token: ReferenceToken): ReferenceToken => {
+    switch (token.kind) {
+        case "cell":
+            return token.absRow || token.absCol ? token : { ...token, row: token.col, col: token.row }
+        case "range":
+            return token.start.absRow || token.start.absCol || token.end.absRow || token.end.absCol ? token : { ...token, start: swapCellEnd(token.start), end: swapCellEnd(token.end) }
+        case "column":
+            return token.start.abs || token.end.abs ? token : { ...token, kind: "row", start: { row: token.start.col, abs: false }, end: { row: token.end.col, abs: false } }
+        case "row":
+            return token.start.abs || token.end.abs ? token : { ...token, kind: "column", start: { col: token.start.row, abs: false }, end: { col: token.end.row, abs: false } }
+    }
+}
+
+/**
+ * Rotates the relative references of one cell-relative R1C1 formula (`R[a]C[b]` ⇒ `R[b]C[a]`)
+ * through the A1 scanner: resolve at the pivot, rotate each token, re-encode at the pivot.
+ * Returns the same string when nothing rotates.
+ * セル相対 R1C1 数式 1 つの相対参照を回転 (`R[a]C[b]` ⇒ `R[b]C[a]`): 支点で A1 へ解決し、各
+ * トークンを回転し、支点で再符号化。回転する参照が無ければ同じ文字列。
+ */
+const transposeFormula = (formula: string): string => {
+    const a1 = fromR1C1(formula, TRANSPOSE_PIVOT)
+    const spans = tokenizeFormula(a1)
+    let out = ""
+    let last = 0
+    let changed = false
+    for (const span of spans) {
+        const rotated = rotateToken(span.token)
+        // 据え置きトークンは原文区間ごと残す (再直列化しない)
+        if (rotated === span.token) {
+            continue
+        }
+        out += `${a1.slice(last, span.start)}${formatReference(rotated)}`
+        last = span.end
+        changed = true
+    }
+    if (!changed) {
+        return formula
+    }
+    return toR1C1(`${out}${a1.slice(last)}`, TRANSPOSE_PIVOT)
+}
+
+/** The cell at (row, col) of a payload — blank when the row is ragged / missing. / payload の (row, col) のセル — 行が欠けていれば空白。 */
+const cellAt = (payload: ClipPayload, row: number, col: number): ClipCell => {
+    const line = payload.cells[row]
+    if (line === undefined) {
+        return BLANK_CELL
+    }
+    const cell = line[col]
+    return cell === undefined ? BLANK_CELL : cell
+}
+
+/**
+ * Transposes a payload: rows ↔ cols, (r, c) ↦ (c, r), relative formula offsets rotated, CF
+ * ranges axis-swapped, sizes dropped (axis-bound), dictionaries and clipId by identity. A 1×1
+ * payload that nothing changes is returned by identity.
+ * payload の転置: rows ↔ cols、(r, c) ↦ (c, r)、相対数式差分は回転、CF レンジは軸交換、寸法は
+ * 落とす (軸に束縛)、辞書と clipId は identity。何も変わらない 1×1 は identity で返す。
+ */
+export const transposePayload = (payload: ClipPayload): ClipPayload => {
+    const { rows, cols } = payload
+    // 1 ジェスチャ 1 メモ: 同じ R1C1 文字列は 1 回だけ回転する
+    const rotate = createFormulaMemo(transposeFormula)
+    // 1×1 で寸法も whole フラグも無く、セルも回転しなければ恒等
+    let unchanged = rows === 1 && cols === 1 && payload.colWidths === undefined && payload.rowHeights === undefined && !payload.wholeRows && !payload.wholeCols
+    const cells: ClipCell[][] = []
+    for (let c = 0; c < cols; c += 1) {
+        const line: ClipCell[] = []
+        for (let r = 0; r < rows; r += 1) {
+            const cell = cellAt(payload, r, c)
+            // 数式のないセルはそのまま、回転しない数式も同一 object
+            let rotated = cell
+            if (cell.f !== undefined) {
+                const f = rotate(cell.f)
+                rotated = f === cell.f ? cell : { ...cell, f }
+            }
+            if (rotated !== cell || cell === BLANK_CELL) {
+                unchanged = false
+            }
+            line.push(rotated)
+        }
+        cells.push(line)
+    }
+    if (unchanged) {
+        return payload
+    }
+    // CF レンジは軸交換 (start ≤ end は保たれる)、規則の他フィールドは identity
+    const conditionalFormats =
+        payload.conditionalFormats.length === 0 ? payload.conditionalFormats : payload.conditionalFormats.map((rule) => ({ ...rule, ranges: rule.ranges.map((range) => ({ startRow: range.startCol, startCol: range.startRow, endRow: range.endCol, endCol: range.endRow })) }))
+    return { v: 1, rows: cols, cols: rows, clipId: payload.clipId, formats: payload.formats, validations: payload.validations, cells, wholeRows: false, wholeCols: false, conditionalFormats }
+}
+
+/** Whether a cell carries an aspect the capabilities do not declare. / 未宣言の側面をセルが持つか。 */
+const hasUndeclared = (cell: ClipCell, c: AspectCapabilities): boolean =>
+    (!c.formula && cell.f !== undefined) || (!c.format && cell.fmt !== undefined) || (!c.validation && cell.val !== undefined) || (!c.note && cell.note !== undefined) || (!c.comments && cell.comments !== undefined) || (!c.hyperlink && cell.link !== undefined)
+
+/** The cell without its undeclared aspects (a fresh object — the caller checked `hasUndeclared`). / 未宣言側面を除いたセル (新 object — 呼び出し側が `hasUndeclared` を確認済み)。 */
+const stripCell = (cell: ClipCell, c: AspectCapabilities): ClipCell => {
+    const stripped: ClipCell = { t: cell.t }
+    if (c.formula && cell.f !== undefined) {
+        stripped.f = cell.f
+    }
+    if (c.format && cell.fmt !== undefined) {
+        stripped.fmt = cell.fmt
+    }
+    if (c.validation && cell.val !== undefined) {
+        stripped.val = cell.val
+    }
+    if (c.note && cell.note !== undefined) {
+        stripped.note = cell.note
+    }
+    if (c.comments && cell.comments !== undefined) {
+        stripped.comments = cell.comments
+    }
+    if (c.hyperlink && cell.link !== undefined) {
+        stripped.link = cell.link
+    }
+    return stripped
+}
+
+/**
+ * The write gate: strips every aspect the adapter does not declare BEFORE tiling — `f`, `fmt`
+ * (+ the `formats` dictionary), `val` (+ `validations`), `note`, `comments`, `link`,
+ * `conditionalFormats`. Untouched cells, rows and dictionaries keep their identity; a payload
+ * with nothing to strip is returned by identity. Sizes are not an aspect (resizeTracks always
+ * exists).
+ * 書込ゲート: アダプタが宣言しない側面を tiling 前に除去 — `f`、`fmt` (+ `formats` 辞書)、`val`
+ * (+ `validations`)、`note`、`comments`、`link`、`conditionalFormats`。触れないセル / 行 / 辞書は
+ * identity を保ち、除去対象の無い payload は identity で返す。寸法は側面ではない (resizeTracks は
+ * 常に在る)。
+ */
+export const stripUndeclaredAspects = (payload: ClipPayload, capabilities: AspectCapabilities): ClipPayload => {
+    let changed = false
+    const cells: (readonly ClipCell[])[] = []
+    for (const line of payload.cells) {
+        // 行内に除去対象が無ければ行配列ごと identity
+        let lineChanged = false
+        const stripped: ClipCell[] = []
+        for (const cell of line) {
+            if (hasUndeclared(cell, capabilities)) {
+                stripped.push(stripCell(cell, capabilities))
+                lineChanged = true
+            } else {
+                stripped.push(cell)
+            }
+        }
+        if (lineChanged) {
+            changed = true
+        }
+        cells.push(lineChanged ? stripped : line)
+    }
+    // 辞書は未宣言なら空へ (既に空なら identity)
+    const formats = !capabilities.format && payload.formats.length > 0 ? [] : payload.formats
+    const validations = !capabilities.validation && payload.validations.length > 0 ? [] : payload.validations
+    const conditionalFormats = !capabilities.cf && payload.conditionalFormats.length > 0 ? [] : payload.conditionalFormats
+    if (formats !== payload.formats || validations !== payload.validations || conditionalFormats !== payload.conditionalFormats) {
+        changed = true
+    }
+    if (!changed) {
+        return payload
+    }
+    return { ...payload, formats, validations, conditionalFormats, cells }
+}
+
+/** Per-payload canonical format dictionary (and its borderless twin), built once. / payload 毎の正準書式辞書 (と罫線なし版)、1 回だけ構築。 */
+type FormatCache = { readonly canonical: readonly (CellFormat | undefined)[]; readonly borderless: readonly (CellFormat | undefined)[] }
+
+/** Canonical dictionaries per payload object (a payload is treated as immutable). / payload object 毎の正準辞書 (payload は不変扱い)。 */
+const formatCaches = new WeakMap<ClipPayload, FormatCache>()
+
+/** The canonical dictionaries of a payload, built on first use. / payload の正準辞書 (初回使用時に構築)。 */
+const formatCacheOf = (payload: ClipPayload): FormatCache => {
+    const hit = formatCaches.get(payload)
+    if (hit !== undefined) {
+        return hit
+    }
+    // 辞書 1 項目 = 1 正準 object: 参照する全セルが identity を共有する
+    const canonical = payload.formats.map((format) => canonicalizeFormat(format))
+    const borderless = canonical.map((format) => (format === undefined || format.borders === undefined ? format : canonicalizeFormat({ ...format, borders: undefined })))
+    const built: FormatCache = { canonical, borderless }
+    formatCaches.set(payload, built)
+    return built
+}
+
+/**
+ * The dictionary entry an optional cell index addresses — undefined for an absent index or one
+ * outside the dictionary (total: never a throw, never a substitute; JS indexing already yields
+ * undefined for a negative / fractional / out-of-range index, so no extra guard is observable).
+ * 任意のセル索引が指す辞書項目 — 索引不在 / 辞書外は undefined (全域: throw も代替もしない。負 /
+ * 小数 / 範囲外の索引は JS の添字が既に undefined を返すので、余分な門番は観測不能)。
+ */
+const entryAt = <T>(entries: readonly T[], index: number | undefined): T | undefined => (index === undefined ? undefined : entries[index])
+
+/**
+ * The format aspect of a source cell under a format-carrying mode: the canonical dictionary
+ * entry (null when the source has none); under `noBorders` the borderless entry merged with the
+ * target's existing borders (the only target-format read).
+ * 書式を運ぶモードでのソースセルの書式側面: 正準辞書項目 (ソースに無ければ null)、`noBorders` では
+ * 罫線なし項目にターゲットの既存罫線を合成したもの (唯一のターゲット書式読み)。
+ */
+const resolveFormat = (payload: ClipPayload, cell: ClipCell, borders: boolean, target: PasteTarget): CellFormat | null => {
+    const cache = formatCacheOf(payload)
+    if (borders) {
+        const canonical = entryAt(cache.canonical, cell.fmt)
+        return canonical === undefined ? null : canonical
+    }
+    // noBorders: ソースの罫線を落とし、ターゲットの既存罫線を保つ
+    const source = entryAt(cache.borderless, cell.fmt)
+    const existing = target.readFormat()
+    const existingBorders = existing === undefined ? undefined : existing.borders
+    if (existingBorders === undefined) {
+        return source === undefined ? null : source
+    }
+    const merged = canonicalizeFormat(source === undefined ? { borders: existingBorders } : { ...source, borders: existingBorders })
+    return merged === undefined ? null : merged
+}
+
+/**
+ * The text aspect of a source cell: the operation result (null = leave the target), the formula
+ * resolved at the target under a formula-carrying mode, else the value text.
+ * ソースセルの text 側面: 演算結果 (null = 触らない)、数式を運ぶモードならターゲットで解決した数式、
+ * それ以外は値文字列。
+ */
+const resolveText = (cell: ClipCell, formula: boolean, target: PasteTarget, operation: PasteOperation | undefined): string | null => {
+    // 数式を運ばないモードでは数式は不可視 — 値だけのセルとして扱う
+    const visible = formula || cell.f === undefined ? cell : { t: cell.t }
+    if (operation !== undefined) {
+        return applyOperation(target.readText(), visible, operation, target)
+    }
+    return visible.f === undefined ? visible.t : fromR1C1(visible.f, target)
+}
+
+/**
+ * Builds the CellPatch for one target cell from a source cell per `MODE_ASPECTS[options.mode]`
+ * ∧ `capabilities` (rules in the fileoverview): skip-blanks first, text (with the operation),
+ * format (or the inject-into-empty injection), note, comments, hyperlink, validation — each
+ * written as its value or `null` when the source lacks it. Null when the patch would carry no
+ * key. `target.readText` is called at most once and only for an operation or the inject check;
+ * `target.readFormat` only under `noBorders`.
+ * ソースセル 1 つから `MODE_ASPECTS[options.mode]` ∧ `capabilities` に従いターゲット 1 セルの
+ * CellPatch を組む (規則は fileoverview): 空白スキップ、text (演算込み)、format (または空セル
+ * 注入)、note、comments、hyperlink、validation — 各々ソースに無ければ `null`。キーが 1 つも
+ * 無ければ null。`target.readText` は演算か注入判定でだけ最大 1 回、`target.readFormat` は
+ * `noBorders` だけが呼ぶ。
+ */
+export const patchFromClipCell = (cell: ClipCell, payload: ClipPayload, target: PasteTarget, options: PasteOptions, capabilities: AspectCapabilities): CellPatch | null => {
+    const aspects = MODE_ASPECTS[options.mode]
+    // 唯一のセル単位スキップ: 空白ソースはどのモードでもターゲットを触らない
+    if (options.skipBlanks === true && isBlankCell(cell)) {
+        return null
+    }
+    const patch: CellPatch = {}
+    let written = false
+    if (aspects.text) {
+        const text = resolveText(cell, aspects.formula && capabilities.formula, target, options.operation)
+        if (text !== null) {
+            patch.text = text
+            written = true
+        }
+    }
+    if (capabilities.format) {
+        if (aspects.format) {
+            patch.format = resolveFormat(payload, cell, aspects.borders, target)
+            written = true
+        } else if (options.injectIntoEmpty === true && cell.fmt !== undefined && target.readText() === "") {
+            // 空ターゲットにだけソース書式を注入 (ソースに書式が無ければ何も書かない)
+            const injected = entryAt(formatCacheOf(payload).canonical, cell.fmt)
+            if (injected !== undefined) {
+                patch.format = injected
+                written = true
+            }
+        }
+    }
+    if (aspects.note && capabilities.note) {
+        patch.note = cell.note === undefined ? null : cell.note
+        written = true
+    }
+    if (aspects.comments && capabilities.comments) {
+        patch.comments = cell.comments === undefined ? null : cell.comments
+        written = true
+    }
+    if (aspects.hyperlink && capabilities.hyperlink) {
+        patch.hyperlink = cell.link === undefined ? null : cell.link
+        written = true
+    }
+    if (aspects.validation && capabilities.validation) {
+        const rule = entryAt(payload.validations, cell.val)
+        patch.validation = rule === undefined ? null : rule
+        written = true
+    }
+    return written ? patch : null
+}
+
+/**
+ * Translates every origin-relative range of every rule by every tile origin and merges the
+ * results into ONE input per source rule (rule order kept; condition / style by identity;
+ * `stopIfTrue` only when present). An empty rule list is returned by identity; no tiles ⇒ [].
+ * Ranges are not clipped to the grid.
+ * 各規則の原点相対レンジを各タイル原点で平行移動し、ソース規則毎に 1 入力へ統合 (規則順維持、
+ * condition / style は identity、`stopIfTrue` は在るときだけ)。空の規則列は identity、タイル無しは
+ * []。グリッドへの切り詰めはしない。
+ */
+export const translateConditionalFormats = (rules: readonly ConditionalFormatRuleInput[], tiles: readonly CellCoord[]): readonly ConditionalFormatRuleInput[] => {
+    if (rules.length === 0) {
+        return rules
+    }
+    if (tiles.length === 0) {
+        return []
+    }
+    return rules.map((rule) => {
+        // タイル順 × レンジ順で平行移動した全レンジを 1 規則へ
+        const ranges = []
+        for (const tile of tiles) {
+            for (const range of rule.ranges) {
+                ranges.push({ startRow: tile.row + range.startRow, startCol: tile.col + range.startCol, endRow: tile.row + range.endRow, endCol: tile.col + range.endCol })
+            }
+        }
+        return { ...rule, ranges }
+    })
+}