@aiquants/spreadsheet 0.8.0

package/src/clipboard/tiling.ts

@@ -0,0 +1,370 @@
+/**
+ * @fileoverview Paste / fill expansion rules. Paste (§6.5.3 contract table): single-cell
+ * target expands the source once from active; an exact-multiple range target tiles the
+ * pattern; a non-multiple range target expands once from the range's top-left (Sheets-style
+ * deviation — Excel raises a dialog). The table is implemented ONCE by the generic tiler
+ * `tileCells<T>` (spec 03 §4, v0.8): the string entry point `expandPaste` and the rich paste
+ * entry point `expandRichPaste` both delegate to it, so a cell of any type is tiled by the
+ * same loop, visited in row-major order over the WHOLE output rectangle (never per tile), and
+ * every visit receives the origin of the tile the cell belongs to (one shared object per tile —
+ * the conditional-format translation moves rule ranges by these origins). `tileCells` returns
+ * the tile origins it entered (a tile whose origin lies inside the grid, even when the grid edge
+ * clips part of it). Grid-edge clipping is silent (the §6.5.3 deviation). estimatePasteCellCount
+ * pre-checks WITHOUT materializing (ADR-12). The private expandCutPaste is the cut-move path:
+ * never tiles, and the CALLER rejects grid-edge clipping. Fill (§8.3, barrel-PRIVATE):
+ * expandFill fills every box cell OUTSIDE the source with 2D source-start modular anchoring
+ * (single-axis bands and diagonal L-shapes share one formula — v0.3), generic over the source
+ * cell type with a per-target emitter (v0.8); estimateFillCellCount pre-checks region + needed
+ * source reads before any readCell call. readFillSource / fillSourceEdit are the ONE per-source
+ * rule of every fill path (the handle drag through expandFill, fillDown / fillRight /
+ * fillSelection through their own target lists): the editor seed (formula source or canonical
+ * text) plus every DECLARED aspect, comments never, a formula shifted per target.
+ *
+ * 貼り付け / fill 展開規則。貼り付け (§6.5.3 の契約表): 単一セル = active 起点で 1 回展開、
+ * 整数倍レンジ = タイル、非整数倍レンジ = レンジ左上起点で 1 回展開 (Sheets 準拠の逸脱)。
+ * 表の実装は generic タイラー `tileCells<T>` の 1 箇所 (spec 03 §4、v0.8): 文字列入口
+ * `expandPaste` とリッチ入口 `expandRichPaste` が委譲するため、任意型のセルが同じループで
+ * 展開され、訪問順は出力矩形全体の行優先 (タイル毎ではない)、各訪問はそのセルが属する
+ * タイルの原点 (タイル毎に 1 つの共有 object — 条件付き書式のレンジ平行移動が使う) を
+ * 受け取る。`tileCells` は入ったタイルの原点 (原点がグリッド内のタイル — 端で一部が切れても
+ * 残る) を返す。グリッド外は静かに切り捨て (§6.5.3 の逸脱)。estimatePasteCellCount は
+ * 展開せず事前見積もる (ADR-12)。expandCutPaste は cut-move 専用 (タイルしない — グリッド外
+ * クリップの拒否は呼び出し側 §6.5.4-4)。fill (§8.3 — barrel 非公開): expandFill はソース
+ * 開始端 anchoring の 2D 剰余式で「バウンディングボックス − ソース」へ展開 (単軸帯も斜め
+ * L 字も同一式 — v0.3 の斜めフィル) し、ソースセル型に generic で対象毎の emitter を受ける
+ * (v0.8)、estimateFillCellCount は readCell 前に領域 + 必要ソース読みを見積もる。
+ * readFillSource / fillSourceEdit は全 fill 経路 (ハンドルドラッグは expandFill 経由、fillDown /
+ * fillRight / fillSelection は自前の対象列) が共有する**唯一**のソース毎規則: エディタの種
+ * (数式ソースか正準文字列) + 宣言済み側面の全部、comments は決して運ばず、数式は対象毎にシフト。
+ */
+
+import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
+import { type CellCoord, type CellRange, rangeSize } from "../model/cellCoord.ts"
+import { type CellFormat, canonicalizeFormat } from "../model/cellFormat.ts"
+import { type CellEdit, resolveEditText, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import type { DataValidationRule } from "../model/dataValidation.ts"
+import { shiftFormula } from "../model/formulaRefs.ts"
+
+/** Paste cell count WITHOUT materializing (ADR-12 pre-check). / 展開せず貼り付け対象セル数を見積もる (ADR-12 の事前検査)。 */
+export const estimatePasteCellCount = (source: readonly (readonly string[])[], target: CellRange): number => {
+    const srcRows = source.length
+    const srcCols = source[0]?.length ?? 0
+    if (srcRows === 0 || srcCols === 0) {
+        return 0
+    }
+    const size = rangeSize(target)
+    const isTileTarget = !(size.rows === 1 && size.cols === 1) && size.rows % srcRows === 0 && size.cols % srcCols === 0
+    return isTileTarget ? size.rows * size.cols : srcRows * srcCols
+}
+
+/**
+ * Generic tiler — the §6.5.3 table over any cell type (spec 03 §4, v0.8): the one construction
+ * point the string paste and the rich paste both delegate to. Visits every output cell in
+ * row-major order over the WHOLE output rectangle (the v0.7 flat-loop order — not tile by tile)
+ * with `(row, col, cell, tile)`: `cell` is the source element itself (same reference, never
+ * copied) and `tile` is the origin of the tile the cell belongs to — ONE object per tile shared
+ * by all of its cells and returned in the result. The grid edge clips silently (the copy-path
+ * deviation): the output rectangle is clamped to the grid before visiting, so a tile whose
+ * origin is inside the grid is entered (and returned) even when only part of it fits, and a
+ * tile entirely outside is never entered. Empty source (no rows or no columns) visits nothing
+ * and returns no tiles. Returns the tile origins in the same row-major order.
+ * generic タイラー — §6.5.3 の表を任意セル型で (spec 03 §4、v0.8)。文字列貼り付けとリッチ
+ * 貼り付けが委譲する唯一の構築点。出力矩形全体の行優先 (v0.7 のフラットループ順 — タイル毎
+ * ではない) で全セルを `(row, col, cell, tile)` で訪問: `cell` はソース要素そのもの (同一参照、
+ * 複製なし)、`tile` はそのセルが属するタイルの原点 — タイル毎に 1 object を全セルで共有し
+ * 戻り値にも載せる。グリッド端は静かに切り捨て (copy 経路の逸脱): 出力矩形を訪問前に
+ * グリッドへクランプするため、原点がグリッド内のタイルは一部しか収まらなくても入り (戻り値
+ * にも載り)、全体が外のタイルには入らない。空ソース (行なし / 列なし) は訪問なし・タイル
+ * なし。戻り値は入ったタイルの原点 (同じ行優先順)。
+ */
+export const tileCells = <T>(source: readonly (readonly T[])[], target: CellRange, active: CellCoord, rowCount: number, colCount: number, visit: (row: number, col: number, cell: T, tile: CellCoord) => void): CellCoord[] => {
+    const srcRows = source.length
+    const srcCols = source[0]?.length ?? 0
+    if (srcRows === 0 || srcCols === 0) {
+        return []
+    }
+    const size = rangeSize(target)
+    const isSingleTarget = size.rows === 1 && size.cols === 1
+    const isTileTarget = !isSingleTarget && size.rows % srcRows === 0 && size.cols % srcCols === 0
+    const outRows = isTileTarget ? size.rows : srcRows
+    const outCols = isTileTarget ? size.cols : srcCols
+    // 基点: 単一セル選択なら active、それ以外は現在レンジの左上 (表の規則そのもの)
+    const origin = isSingleTarget ? active : { row: target.startRow, col: target.startCol }
+    // グリッド外は切り捨て (逸脱 — Excel は拒否。§6.5.3 の表参照): 出力矩形をグリッド境界でクランプ
+    const rowEnd = Math.min(outRows, rowCount - origin.row)
+    const colEnd = Math.min(outCols, colCount - origin.col)
+    const tiles: CellCoord[] = []
+    for (let r0 = 0; r0 < rowEnd; r0 += srcRows) {
+        // このタイル行の原点をタイル毎に 1 object だけ作る (同一タイルの全セルへ同じ参照を渡す)
+        const rowTiles: CellCoord[] = []
+        for (let c0 = 0; c0 < colEnd; c0 += srcCols) {
+            const tile = { row: origin.row + r0, col: origin.col + c0 }
+            rowTiles.push(tile)
+            tiles.push(tile)
+        }
+        // 訪問順は矩形全体の行優先 (タイル毎の塊ではない — v0.7 のフラットループと同一順序)
+        const rowSpan = Math.min(srcRows, rowEnd - r0)
+        for (let rr = 0; rr < rowSpan; rr += 1) {
+            const row = origin.row + r0 + rr
+            const sourceRow = source[rr]
+            for (let j = 0; j < rowTiles.length; j += 1) {
+                const c0 = j * srcCols
+                const colSpan = Math.min(srcCols, colEnd - c0)
+                for (let cc = 0; cc < colSpan; cc += 1) {
+                    visit(row, origin.col + c0 + cc, sourceRow[cc], rowTiles[j])
+                }
+            }
+        }
+    }
+    return tiles
+}
+
+/**
+ * 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 const expandPaste = (source: readonly (readonly string[])[], target: CellRange, active: CellCoord, rowCount: number, colCount: number): CellEdit[] => {
+    const edits: CellEdit[] = []
+    tileCells(source, target, active, rowCount, colCount, (row, col, text) => {
+        edits.push({ row, col, text })
+    })
+    return edits
+}
+
+/**
+ * Rich paste expansion (spec 03 §4, v0.8): tiles a cell matrix of any type with `tileCells`,
+ * asks `toPatch(cell, row, col, tile)` for the per-cell patch and returns the edits
+ * `{ ...patch, row, col }` (the coordinates are authoritative — a patch key can never override
+ * them) together with the tile origins for the conditional-format translation. A `null` patch
+ * skips that cell (the only per-cell skip — `skipBlanks`); the tile origin stays in `tiles`
+ * regardless, because rule ranges are a tile-level aspect, not a cell-level one. Edits keep
+ * the row-major visiting order. Independent of the wire format by design: the caller passes
+ * the payload's cell matrix.
+ * リッチ貼り付け展開 (spec 03 §4、v0.8)。任意型のセル行列を `tileCells` でタイルし、
+ * `toPatch(cell, row, col, tile)` にセル毎のパッチを求め、edits `{ ...patch, row, col }`
+ * (座標が正 — パッチのキーでは上書き不能) と条件付き書式平行移動用のタイル原点を返す。
+ * `null` パッチはそのセルを書かない (唯一のセル単位スキップ — `skipBlanks`) が、規則レンジは
+ * セルでなくタイルの側面なのでタイル原点は `tiles` に残る。edits は行優先の訪問順のまま。
+ * wire format から独立 (呼び出し側が payload のセル行列を渡す)。
+ */
+export const expandRichPaste = <C, P extends object>(
+    cells: readonly (readonly C[])[],
+    target: CellRange,
+    active: CellCoord,
+    rowCount: number,
+    colCount: number,
+    toPatch: (cell: C, row: number, col: number, tile: CellCoord) => P | null,
+): { edits: (CellCoord & P)[]; tiles: CellCoord[] } => {
+    const edits: (CellCoord & P)[] = []
+    const tiles = tileCells(cells, target, active, rowCount, colCount, (row, col, cell, tile) => {
+        const patch = toPatch(cell, row, col, tile)
+        // null = このセルは書かない (skipBlanks 等の唯一のセル単位スキップ) — タイル原点は tiles に残る
+        if (patch === null) {
+            return
+        }
+        // 座標が正: パッチに row / col が紛れても上書きされない
+        edits.push({ ...patch, row, col })
+    })
+    return { edits, tiles }
+}
+
+/**
+ * Validates the fill box (§8.3 SSOT): the box must strictly CONTAIN the source and differ
+ * from it — anything else is a caller bug and fail-fasts (no direction argument, no partial
+ * overlap; the box is derived from source ∪ hover so containment is structural).
+ * fill ボックスの検証 (§8.3 の SSOT)。ボックスはソースを包含しかつ相違すること — それ以外は
+ * 呼び出し側バグとして fail-fast (direction 引数なし・部分重なりなし。ボックスは
+ * ソース ∪ hover 由来のため包含は構造的)。
+ */
+const assertFillBox = (sourceRange: CellRange, box: CellRange): void => {
+    const contains = box.startRow <= sourceRange.startRow && box.endRow >= sourceRange.endRow && box.startCol <= sourceRange.startCol && box.endCol >= sourceRange.endCol
+    const differs = box.startRow !== sourceRange.startRow || box.endRow !== sourceRange.endRow || box.startCol !== sourceRange.startCol || box.endCol !== sourceRange.endCol
+    if (!(contains && differs)) {
+        throw new RangeError(`[spreadsheet] expandFill requires a box strictly containing the source (source ${JSON.stringify(sourceRange)}, box ${JSON.stringify(box)})`)
+    }
+}
+
+/**
+ * Fill cell count BEFORE any source read (ADR-12 §8.3): region cells (box minus source) plus
+ * the distinct source cells the expansion will read — rows side: all source rows when the box
+ * extends horizontally, else min(source rows, extra rows); columns side symmetric. For pure
+ * single-axis bands this reduces EXACTLY to the v0.2 formula (band + orthogonal span x
+ * min(source length, band length)); the diagonal case charges the full source block. The
+ * charge is an UPPER BOUND on distinct reads (a diagonal whose extension is smaller than the
+ * source on both axes reads fewer distinct cells) — it never under-counts. The rejection
+ * count the machine reports is THIS SUM (documented asymmetry vs the other ops).
+ * readCell 前の fill セル数見積もり (ADR-12 §8.3): 領域セル (ボックス − ソース) + ソース読み
+ * 課金 — 行側はボックスが横に伸びるとき全ソース行、さもなくば min(ソース行数, 追加行数)。
+ * 列側は対称。単軸帯では v0.2 の式と厳密一致し、斜めはソース全ブロック課金。課金は実読み
+ * 異種セル数の**上界** (両軸とも拡張がソースより小さい斜めでは実読みがこれを下回る) で
+ * 過小計上はしない。拒否 count はこの和 (他 op との非対称は文書化)。
+ */
+export const estimateFillCellCount = (sourceRange: CellRange, box: CellRange): number => {
+    assertFillBox(sourceRange, box)
+    const boxSize = rangeSize(box)
+    const srcSize = rangeSize(sourceRange)
+    const extraRows = boxSize.rows - srcSize.rows
+    const extraCols = boxSize.cols - srcSize.cols
+    const rowsRead = extraCols > 0 ? srcSize.rows : Math.min(srcSize.rows, extraRows)
+    const colsRead = extraRows > 0 ? srcSize.cols : Math.min(srcSize.cols, extraCols)
+    return boxSize.rows * boxSize.cols - srcSize.rows * srcSize.cols + rowsRead * colsRead
+}
+
+/**
+ * Expands a fill box into cell edits for every cell of the box OUTSIDE the source (§8.3 —
+ * copy fill only), generic over the source cell type (v0.8): `readCell` resolves one source
+ * cell (a string for a text fill, a {@link FillSource} for the rich fill) and
+ * `toEdit(value, origin, target)` turns it into the edit of one target cell — `origin` is the
+ * source cell the target maps to, so a formula can shift by `target − origin`. ONE 2D
+ * source-start modular anchoring formula for all directions incl. diagonals:
+ * src[((r - srcStart) % m + m) % m][((c - colStart) % n + n) % n] — an upward / leftward fill
+ * continues the cycle in reverse (Excel's reversed pattern continuation) and a diagonal fill
+ * tiles the source block over the L-shaped region. Reads each needed source cell at most ONCE
+ * (memoized reader hand-off — nothing materializes beyond the estimate; one shared origin
+ * object per source cell).
+ * fill ボックスの CellEdit 展開 (§8.3 — copy fill のみ)。ソースセル型に generic (v0.8): `readCell` が
+ * ソースセル 1 個を解決 (text fill は文字列、リッチ fill は {@link FillSource}) し、
+ * `toEdit(value, origin, target)` が対象 1 セルの edit を作る — `origin` は対象が写像されるソース
+ * セルで、数式は `target − origin` だけシフトできる。ソース外の全ボックスセルへ、単軸も斜めも
+ * 共通の 2D ソース開始端 anchoring 剰余式で展開。上 / 左方向は循環の逆向き継続 (Excel 一致)、
+ * 斜めは L 字領域へソースブロックをタイル。ソースセルは高々 1 回だけ読む (メモ化 reader
+ * 受け渡し — 見積もり超の実体化なし。原点 object はソースセル毎に 1 つを共有)。
+ */
+export const expandFill = <T>(readCell: (row: number, col: number) => T, sourceRange: CellRange, box: CellRange, toEdit: (value: T, origin: CellCoord, target: CellCoord) => CellEdit): CellEdit[] => {
+    assertFillBox(sourceRange, box)
+    const m = rangeSize(sourceRange).rows
+    const n = rangeSize(sourceRange).cols
+    const edits: CellEdit[] = []
+    // 必要ソースは高々 1 回だけ読む (剰余で再訪するセルを再読みしない — 見積もりの読み数と一致)
+    const cache = new Map<number, { value: T; origin: CellCoord }>()
+    for (let row = box.startRow; row <= box.endRow; row += 1) {
+        const srcRow = sourceRange.startRow + ((((row - sourceRange.startRow) % m) + m) % m)
+        const inRowSpan = row >= sourceRange.startRow && row <= sourceRange.endRow
+        for (let col = box.startCol; col <= box.endCol; col += 1) {
+            // ソース内セルは書かない (自己書込なし — 領域 = ボックス − ソース)
+            if (inRowSpan && col >= sourceRange.startCol && col <= sourceRange.endCol) {
+                continue
+            }
+            const srcCol = sourceRange.startCol + ((((col - sourceRange.startCol) % n) + n) % n)
+            // 2^21 = 2,097,152 列が合成キーの衝突限界 (実証封筒 16,384 列の 128 倍 — §9 の
+            // 上限を桁で超える列数は想定外。超えると別ソースセルが同一キーへ黙って畳まれる)
+            const key = srcRow * 2 ** 21 + srcCol
+            let entry = cache.get(key)
+            if (entry === undefined) {
+                entry = { value: readCell(srcRow, srcCol), origin: { row: srcRow, col: srcCol } }
+                cache.set(key, entry)
+            }
+            edits.push(toEdit(entry.value, entry.origin, { row, col }))
+        }
+    }
+    return edits
+}
+
+/**
+ * One fill source cell resolved ONCE (spec 08 §4 fill row, v0.8): `text` / `isFormula` is the
+ * editor seed (`resolveEditText` — the formula source when `getCellFormula` is declared and the
+ * cell holds one, else the canonical text; a formula not starting with "=" is that function's
+ * RangeError), and each DECLARED aspect rides as a key in the `CellPatch` vocabulary — an absent
+ * key means the capability is undeclared (the target's aspect stays untouched), `null` means
+ * declared but empty on the source (the target's aspect is cleared), `format` is the canonical
+ * form. Comments never travel (README deviation table).
+ * fill のソースセル 1 個の 1 回解決 (分冊 08 §4 の fill 行、v0.8): `text` / `isFormula` はエディタの種
+ * (`resolveEditText` — `getCellFormula` 宣言 + 数式ありなら数式ソース、さもなくば正準文字列。"=" 非
+ * 始まりの数式は同関数の RangeError)、宣言済み側面だけが `CellPatch` 語彙のキーで乗る — キー不在 =
+ * 能力未宣言 (対象の側面は不変)、`null` = 宣言済みだがソースに無い (対象の側面を消去)、`format` は
+ * 正準形。comments は決して運ばない (README 逸脱表)。
+ */
+export type FillSource = { text: string; isFormula: boolean; format?: CellFormat | null; validation?: DataValidationRule | null; hyperlink?: string | null; note?: string | null }
+
+/**
+ * Reads one fill source cell through the adapter's declared capabilities: the editor seed first
+ * (its RangeError fires before any aspect read), then format / validation / hyperlink / note —
+ * only the declared ones, never comments. The hyperlink read is the trust boundary (ADR-10):
+ * `normalizeAdapterHyperlink` maps an allowlist-failing URL to a link-less source (`null`).
+ * アダプタの宣言済み能力で fill ソースセル 1 個を読む: まずエディタの種 (その RangeError は側面読みより
+ * 先に立つ)、次に format / validation / hyperlink / note — 宣言済みだけ、comments は決して読まない。
+ * hyperlink の読みは信頼境界 (ADR-10) — `normalizeAdapterHyperlink` が許可リスト外の URL をリンク
+ * 無しソース (`null`) へ写す。
+ */
+export const readFillSource = (adapter: SpreadsheetDataAdapter, row: number, col: number): FillSource => {
+    // 種はエディタと同じ解決 (数式は "=" 始まり必須 — 非 "=" は側面を読む前に RangeError で fail-fast)
+    const seed = resolveEditText(adapter, row, col)
+    const source: FillSource = { text: seed.text, isFormula: seed.isFormula }
+    // 宣言済み側面だけキーを持つ (未宣言側面のキーは出さない)。ソースに無ければ消去 (null)
+    if (adapter.getCellFormat !== undefined) {
+        const format = adapter.getCellFormat(row, col)
+        // CellPatch.format は正準形の全体 (無書式は null で消去)
+        source.format = format === undefined ? null : canonicalizeFormat(format)
+    }
+    if (adapter.getCellValidation !== undefined) {
+        const validation = adapter.getCellValidation(row, col)
+        source.validation = validation === undefined ? null : validation
+    }
+    if (adapter.getCellHyperlink !== undefined) {
+        // 信頼境界 (ADR-10): 生 URL を許可リストへ正規化 — 正規化不能はソースにリンク無し (null = 対象の側面を消去)
+        const hyperlink = normalizeAdapterHyperlink(adapter.getCellHyperlink(row, col))
+        source.hyperlink = hyperlink === undefined ? null : hyperlink
+    }
+    if (adapter.getCellNote !== undefined) {
+        const note = adapter.getCellNote(row, col)
+        source.note = note === undefined ? null : note
+    }
+    return source
+}
+
+/**
+ * The edit of one fill target from a source resolved at `origin`: a formula shifts its relative
+ * references by `target − origin` (`shiftFormula`), plain text is copied verbatim, and every
+ * aspect key the source carries is copied as is (absent keys stay absent — a v0.7 adapter yields
+ * exactly `{ row, col, text }`).
+ * 原点 `origin` で解決したソースから対象 1 セルの edit: 数式は `target − origin` だけ相対参照を
+ * シフト (`shiftFormula`)、素の text はそのまま、ソースが持つ側面キーはそのまま複製 (不在キーは不在の
+ * まま — v0.7 アダプタは `{ row, col, text }` ちょうど)。
+ */
+export const fillSourceEdit = (source: FillSource, origin: CellCoord, target: CellCoord): CellEdit => {
+    // 数式は相対シフト、それ以外は text をそのまま
+    const edit: CellEdit = { row: target.row, col: target.col, text: source.isFormula ? shiftFormula(source.text, target.row - origin.row, target.col - origin.col) : source.text }
+    // 側面キーはソースの有無をそのまま写す (宣言済み側面だけがキーを持つ)
+    if (source.format !== undefined) {
+        edit.format = source.format
+    }
+    if (source.validation !== undefined) {
+        edit.validation = source.validation
+    }
+    if (source.hyperlink !== undefined) {
+        edit.hyperlink = source.hyperlink
+    }
+    if (source.note !== undefined) {
+        edit.note = source.note
+    }
+    return edit
+}
+
+/**
+ * Cut-move expansion (§6.5.4-4): the source is written ONCE at origin with its own
+ * dimensions — never tiled. Returns null when any cell would fall outside the grid; the
+ * caller rejects with reason "bounds" (allowing the clip would clear the source and then
+ * silently drop the clipped cells = quiet data loss, unlike the copy path's clip deviation).
+ * cut-move 展開 (§6.5.4-4)。origin へソース寸法で 1 回だけ展開 — タイルしない。グリッド外へ
+ * はみ出す場合は null (呼び出し側が reason "bounds" で拒否 — クリップを許すと clear だけ
+ * されて書かれない静かなデータ喪失になる)。
+ */
+export const expandCutPaste = (source: readonly (readonly string[])[], origin: CellCoord, rowCount: number, colCount: number): CellEdit[] | null => {
+    const srcRows = source.length
+    const srcCols = source[0]?.length ?? 0
+    if (srcRows === 0 || srcCols === 0) {
+        return []
+    }
+    if (origin.row + srcRows > rowCount || origin.col + srcCols > colCount) {
+        return null
+    }
+    const edits: CellEdit[] = []
+    for (let r = 0; r < srcRows; r += 1) {
+        for (let c = 0; c < srcCols; c += 1) {
+            edits.push({ row: origin.row + r, col: origin.col + c, text: source[r][c] })
+        }
+    }
+    return edits
+}

package/src/clipboard/tsv.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Clipboard TSV serialize/parse compatible with Excel's REAL behavior (§6.5.1):
+ * only cells containing a tab or newline are quoted (with internal `"` doubled) — everything
+ * else passes through verbatim even when it contains `"`. The parser therefore adopts the
+ * quoted reading ONLY when the unquoted content itself needs quoting; a field that is merely
+ * wrapped in quotes (`"hi"`) is a literal Excel emitted untouched. Both readers share ONE
+ * grammar walk (`scanTsv`): `parseTsv` materialises the matrix, `measureTsv` only counts rows ×
+ * columns so the ADR-12 paste gate can refuse an over-cap clipboard BEFORE any row array exists
+ * (a newline-only clipboard costs ~hundreds of bytes of matrix per input byte when materialised).
+ *
+ * Excel 実挙動互換のクリップボード TSV (§6.5.1)。quote されるのはタブ / 改行を含むセルだけ
+ * (内部の `"` は二重化)、それ以外は `"` を含んでいても素通し。parse 側の quoted 解釈は
+ * 「剥がした中身が改行かタブを含む」場合のみ採用 — 全体が引用で包まれただけの `"hi"` は
+ * Excel が素通しした literal であり剥がさない。読み手 2 つは唯一の文法走査 (`scanTsv`) を共有:
+ * `parseTsv` は行列を実体化し、`measureTsv` は行 × 列だけを数える — ADR-12 の paste ゲートが
+ * 上限超のクリップボードを行配列の実体化**前**に拒否できる (改行だけのクリップボードは実体化で
+ * 入力 1 byte あたり数百 byte の行列費用になる)。
+ */
+
+/**
+ * Serializes a matrix to Excel-behavior TSV with a trailing CRLF.
+ * 行列を終端 CRLF つきの Excel 実挙動 TSV へ直列化。
+ */
+export const serializeTsv = (matrix: readonly (readonly string[])[]): string =>
+    // 終端 CRLF は必須 (Excel 実挙動)。parseTsv の「終端の改行 1 つを剥がす」規約と対 —
+    // 終端なしだと [["a"],[""]] が [["a"]] に潰れ (cut-move で clear されるべき先に旧値が残る)、
+    // [[""]] は "" になって §6.5.4-5 の空ガードに飲まれ「空セル貼り付けで clear」が不発になる
+    `${matrix.map((row) => row.map(escapeTsvField).join("\t")).join("\r\n")}\r\n`
+
+/** Quotes only fields containing a tab or newline (Excel behavior). / タブか改行を含むフィールドのみ quote (Excel 実挙動)。 */
+const escapeTsvField = (field: string): string => (/[\t\r\n]/.test(field) ? `"${field.replaceAll('"', '""')}"` : field)
+
+/**
+ * Strips the single trailing line terminator (CRLF / LF / lone CR) — the last row's terminator,
+ * not an empty row.
+ * 終端の改行 1 つ (CRLF / LF / 単独 CR) を剥がす — 「最終行の終端」であり空行ではない。
+ */
+const stripTrailingTerminator = (text: string): string => (text.endsWith("\r\n") ? text.slice(0, -2) : text.endsWith("\n") || text.endsWith("\r") ? text.slice(0, -1) : text)
+
+/**
+ * The ONE grammar walk both readers share: reads `body` field by field (the quoted reading
+ * adopted only under the two-part condition below), reporting each field to `onField` and each
+ * row end to `onRowEnd` (the last row included). `body` must be terminator-stripped, non-empty.
+ * 両読み手が共有する唯一の文法走査: `body` を 1 フィールドずつ読み (quoted 解釈の採用は下の
+ * 二重条件のときだけ)、フィールド毎に `onField`、行の終わり毎に `onRowEnd` (最終行も) を呼ぶ。
+ * `body` は終端剥がし済み・非空であること。
+ */
+const scanTsv = (body: string, onField: (field: string) => void, onRowEnd: () => void): void => {
+    let i = 0
+    while (true) {
+        // 1 フィールドずつ読む。quoted 解釈は「" で始まり、対応する閉じの直後がタブ / 改行 / 終端」の
+        // ときだけ採用し、そうでなければ literal (Excel が quote せず出力した `"hi"` を壊さない)
+        let field: string
+        if (body[i] === '"') {
+            const quoted = tryReadQuotedField(body, i)
+            if (quoted !== null) {
+                field = quoted.value
+                i = quoted.nextIndex
+            } else {
+                const end = nextDelimiter(body, i)
+                field = body.slice(i, end)
+                i = end
+            }
+        } else {
+            const end = nextDelimiter(body, i)
+            field = body.slice(i, end)
+            i = end
+        }
+        onField(field)
+        if (i >= body.length) {
+            onRowEnd()
+            return
+        }
+        if (body[i] === "\t") {
+            i += 1
+        } else {
+            // 改行 (CRLF / LF / CR)
+            i += body[i] === "\r" && body[i + 1] === "\n" ? 2 : 1
+            onRowEnd()
+        }
+    }
+}
+
+/**
+ * Parses Excel-behavior TSV into a rectangular matrix (ragged rows are right-padded).
+ * Excel 実挙動 TSV を矩形行列へ解析 (ギザギザ行は右パディング)。
+ */
+export const parseTsv = (text: string): string[][] => {
+    const body = stripTrailingTerminator(text)
+    if (body === "") {
+        return [[""]]
+    }
+    const rows: string[][] = []
+    let row: string[] = []
+    scanTsv(
+        body,
+        (field) => {
+            row.push(field)
+        },
+        () => {
+            rows.push(row)
+            row = []
+        },
+    )
+    // 矩形化: Excel 由来は常に矩形だが、他アプリ由来のギザギザ行も右パディングで受ける (仕様)。
+    // ❗ Math.max(...rows) は行数ぶん引数を積み、巨大貼り付け (V8 実測 ~15 万行、JSC はさらに低い)
+    // で ADR-12 見積もりに到達する前に RangeError で落ちる — ループで求める
+    let width = 0
+    for (const r of rows) {
+        if (r.length > width) {
+            width = r.length
+        }
+    }
+    return rows.map((r) => (r.length === width ? r : [...r, ...Array<string>(width - r.length).fill("")]))
+}
+
+/**
+ * The dimensions `parseTsv(text)` would materialise — rows and the rectangularised (maximum)
+ * column count — from the SAME grammar walk, without building any row array: the ADR-12
+ * pre-materialisation estimate of the `tsv` paste source (a raw line-terminator count would
+ * over-count rows for quoted embedded newlines and falsely reject a legitimate paste).
+ * `parseTsv(text)` が実体化する寸法 — 行数と矩形化後 (最大) の列数 — を**同じ**文法走査から、
+ * 行配列を一切作らずに返す: `tsv` 貼り付けソースの ADR-12 実体化前見積もり (素の改行計数は
+ * quoted 内の埋め込み改行を行と数え、正当な貼り付けを誤って上限拒否する)。
+ */
+export const measureTsv = (text: string): { rows: number; cols: number } => {
+    const body = stripTrailingTerminator(text)
+    if (body === "") {
+        return { rows: 1, cols: 1 }
+    }
+    let rows = 0
+    let cols = 0
+    let current = 0
+    scanTsv(
+        body,
+        () => {
+            current += 1
+        },
+        () => {
+            rows += 1
+            if (current > cols) {
+                cols = current
+            }
+            current = 0
+        },
+    )
+    return { rows, cols }
+}
+
+/** Reads a quoted field at i, adopted ONLY when its content needs quoting. / 位置 i の quoted field 読取り (中身が quote を要する場合のみ採用、不成立は null)。 */
+const tryReadQuotedField = (body: string, start: number): { value: string; nextIndex: number } | null => {
+    let value = ""
+    let i = start + 1
+    while (i < body.length) {
+        if (body[i] === '"') {
+            if (body[i + 1] === '"') {
+                value += '"'
+                i += 2
+            } else {
+                const next = i + 1
+                // 成立条件は 2 つとも必要: (a) 閉じ引用の直後が区切りか終端、
+                // (b) 中身に改行かタブを含む (Excel が quote する唯一の理由)。
+                // (b) が無いと、全体がちょうど引用で包まれた literal `"hi"` を剥がしてしまう
+                const isBoundary = next >= body.length || body[next] === "\t" || body[next] === "\n" || body[next] === "\r"
+                if (isBoundary && /[\t\r\n]/.test(value)) {
+                    return { value, nextIndex: next }
+                }
+                return null
+            }
+        } else {
+            value += body[i]
+            i += 1
+        }
+    }
+    return null // 閉じ引用が無い → literal 扱い
+}
+
+/** Next tab/newline position or end. / 次の区切り位置 (無ければ終端)。 */
+const nextDelimiter = (body: string, from: number): number => {
+    for (let i = from; i < body.length; i += 1) {
+        if (body[i] === "\t" || body[i] === "\n" || body[i] === "\r") {
+            return i
+        }
+    }
+    return body.length
+}