@aiquants/spreadsheet 0.8.0

package/src/clipboard/useClipboard.ts

@@ -0,0 +1,1154 @@
+/**
+ * @fileoverview Clipboard wiring on the sink (§6.5.4, v0.8 §4.2.5 / ADR-14): copy / cut write
+ * three flavours — `text/plain` (raw TSV), `text/html` (the interop table carrying the lossless
+ * payload in `data-aqsp-clip`, its FIRST attribute) and, for the paste EVENT channel only, the
+ * custom MIME `application/x-aqsp-clip` (the same JSON). Paste reads exactly ONE source chosen by
+ * marker detection (`aqsp` → `sheets` → `excel` → `html` → `tsv`), estimates the write BEFORE
+ * materialising anything (ADR-12: header dimensions / HTML estimator / TSV counting scan), and treats a
+ * parse failure of the detected source as `onClipboardUnavailable("unreadable")` — never a slide
+ * to another reader. The armed clip is a ref (no re-render) that records the payload and its
+ * source adapter: an `aqsp` paste whose header `clipId` equals the armed id reuses the armed
+ * payload by identity (no parse, on BOTH channels); a plain paste of an armed CUT is the
+ * non-tiling cut-move (same sheet: one transaction of clears + writes; another sheet: the target
+ * commit first, then the source clears under the SAME transaction id). A paste of the armed
+ * payload itself keeps the clip whatever its kind (Excel keeps the ants across a paste and treats
+ * Paste Special of a cut as copy semantics); a paste of any other source keeps only a copy (v0.7
+ * rule). Paste Special options arrive through `pendingPasteOptionsRef` (event) or `paste(options)`
+ * (menu — `navigator.clipboard.read({ unsanitized: ["text/html"] })`), transforms run in
+ * `pasteSpecial.ts`, tiling in the generic `expandRichPaste`, sizes through `gateResizeEntries`
+ * (non-undo geometry). Every v0.8 parameter is a capability declaration — absent ⇒ the v0.7 branch
+ * byte-for-byte (TSV-only adapters — the commit seam `commitPaste` is the one required member). rearm stays with the setSelection
+ * wrapper (§6.9-1 no-double-actor rule).
+ *
+ * シンク上のクリップボード結線 (§6.5.4、v0.8 §4.2.5 / ADR-14)。copy / cut は 3 フレーバー —
+ * `text/plain` (素の TSV)、`text/html` (lossless payload を先頭属性 `data-aqsp-clip` に運ぶ相互運用
+ * 表)、paste イベント経路専用のカスタム MIME `application/x-aqsp-clip` (同じ JSON) — を書く。
+ * paste はマーカー検出 (`aqsp` → `sheets` → `excel` → `html` → `tsv`) で選んだ唯一のソースを読み、
+ * 実体化前に見積もり (ADR-12: ヘッダ寸法 / HTML 見積もり / TSV 計数走査)、検出ソースの parse 失敗は
+ * `onClipboardUnavailable("unreadable")` — 別 reader へは滑らない。装填クリップは payload と元
+ * アダプタを記録する ref (再レンダーなし): ヘッダ `clipId` が装填 id と一致する `aqsp` 貼り付けは
+ * 両経路とも装填 payload を identity で採用 (parse なし)、装填 CUT の素の貼り付けはタイルしない
+ * cut-move (同一シート: clear + 書込の 1 トランザクション、跨ぎ: 対象 commit → 同一 transaction id
+ * で元 clear)。装填 payload 自身の貼り付けは種別を問わずクリップを保ち (Excel はペースト越しに
+ * アンツを保ち、cut の Paste Special は copy 意味論)、他ソースの貼り付けは copy だけ保つ (v0.7
+ * 規則)。Paste Special は `pendingPasteOptionsRef` (イベント) / `paste(options)` (メニュー —
+ * `navigator.clipboard.read({ unsanitized: ["text/html"] })`) から、変換は `pasteSpecial.ts`、タイル
+ * は generic `expandRichPaste`、寸法は `gateResizeEntries` (非 undo 幾何)。v0.8 のパラメータは全て
+ * 能力宣言 — 不在なら v0.7 分岐そのまま (TSV のみのアダプタ — commit シーム `commitPaste` だけが必須メンバー)。rearm は
+ * setSelection ラッパーの専有 (§6.9-1)。
+ */
+
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import { gateResizeEntries, MAX_TRACK_SIZE_PX, type ResizeEntry, ROW_HIDDEN_LIMIT } from "../header/resizeGates.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { isWholeCols, isWholeRows, normalizeAdapterHyperlink, normalizeHyperlink } from "../model/cellAnnotations.ts"
+import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, rangeSize, type SpreadsheetOperation } from "../model/cellCoord.ts"
+import type { CellFormat } from "../model/cellFormat.ts"
+import type { ConditionalFormatRule, ConditionalFormatRuleInput } from "../model/conditionalFormat.ts"
+import { type AspectCapabilities, aspectCapabilities, type CellEdit, type EditRejection, type EditSource, resolveEditText, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { toR1C1 } from "../model/formulaRefs.ts"
+import type { SelectionState } from "../selection/selectionState.ts"
+import {
+    CLIP_MIME,
+    type ClipCell,
+    type ClipChannel,
+    type ClipFlavours,
+    type ClipFormatInterner,
+    type ClipPayload,
+    type ClipValidationInterner,
+    createFormatInterner,
+    createValidationInterner,
+    detectClipSource,
+    estimateHtmlTableCells,
+    newClipId,
+    readClipPayload,
+    readClipSourceHeader,
+    serializeClipPayload,
+} from "./clipPayload.ts"
+import { parseHtmlTable, serializeHtmlTable } from "./htmlInterop.ts"
+import { DEFAULT_PASTE_OPTIONS, MODE_ASPECTS, type PasteAspects, type PasteOptions, patchFromClipCell, stripUndeclaredAspects, translateConditionalFormats, transposePayload } from "./pasteSpecial.ts"
+import { expandRichPaste } from "./tiling.ts"
+import { measureTsv, parseTsv, serializeTsv } from "./tsv.ts"
+
+/** 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 type ClipInfo = { kind: "copy" | "cut"; range: CellRange; foreign: boolean }
+
+/**
+ * The armed clipboard source (marching-ants marquee state): kind, source range, the clip id the
+ * three flavours carry, the adapter the cells were read from and the payload captured at the
+ * gesture. A COPY pastes that snapshot by identity on a clip-id hit (Sheets semantics); a CUT is
+ * a reference to the range, as in Excel — its cells are re-read from `sourceAdapter` at paste
+ * time (`armedPayload`) so a format / annotate commit applied after Ctrl+X travels with the
+ * move, while the snapshot keeps the identity, the dimensions and the whole-row / whole-column
+ * sizes (the source sheet's axes are not at hand after a sheet switch).
+ * 装填済みクリップボードソース (マーチングアンツの状態): 種別、元レンジ、3 フレーバーが運ぶ
+ * clip id、セルを読んだアダプタ、ジェスチャ時点の payload。copy は clip id 一致でその snapshot を
+ * identity 採用 (Sheets 意味論)、cut は Excel と同じくレンジへの参照 — セルは貼り付け時に
+ * `sourceAdapter` から再読 (`armedPayload`) するので Ctrl+X 後の書式 / 注釈 commit が move に
+ * 同伴し、snapshot は同一性・寸法・全行 / 全列の寸法を保つ (シート切替後は元シートの軸が無い)。
+ */
+export type ClipRecord = { kind: "copy" | "cut"; range: CellRange; clipId: string; sourceAdapter: SpreadsheetDataAdapter; payload: ClipPayload }
+
+/** Why the menu path could not read the clipboard (§1.9 `onClipboardUnavailable`). / メニュー経路がクリップボードを読めなかった理由 (§1.9 `onClipboardUnavailable`)。 */
+export type ClipboardUnavailableCause = "insecure-origin" | "permission-denied" | "empty" | "unreadable"
+
+/** One paste's outcome: the adapter was called / nothing was written / refused (§1.10 `paste`). / 1 回の貼り付けの結果: アダプタが呼ばれた / 何も書かなかった / 拒否 (§1.10 `paste`)。 */
+export type PasteOutcome = "applied" | "empty" | "rejected"
+
+/** The paste-only part of `PasteEditContext` the hook hands to the root's transaction seam. / フックがルートのトランザクションシームへ渡す `PasteEditContext` の貼り付け固有部。 */
+export type PasteSheet = { sameSheet: boolean; conditionalFormats: readonly ConditionalFormatRuleInput[] }
+
+/** The track-size seam (copy reads sizes of whole rows / columns, paste writes them through the gate). / トラック寸法シーム (copy は全行 / 全列の寸法を読み、paste はゲート経由で書く)。 */
+export type ClipboardResizeSeam = { rowAxis: AxisModel; colAxis: AxisModel; resizeTracks: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void }
+
+/** Hook parameters (every v0.8 member is a capability declaration — absent ⇒ v0.7 branch). / フックのパラメータ (v0.8 の各メンバーは能力宣言 — 不在なら v0.7 分岐)。 */
+export type UseClipboardParams = {
+    /** Rewire gate (§6.9-1 empty branch). / 再結線ゲート。 */
+    enabled: boolean
+    sinkRef: RefObject<HTMLTextAreaElement | null>
+    adapter: SpreadsheetDataAdapter
+    isEditing: () => boolean
+    getSelection: () => SelectionState
+    setSelection: (next: SelectionState) => void
+    /**
+     * THE commit seam (ADR-16): commits ONE paste transaction with its sheet context and returns
+     * the transaction id, or null when the adapter rejected (a cross-sheet cut clears the source
+     * under the same id).
+     * 唯一の commit シーム (ADR-16): 貼り付け 1 トランザクションをシート文脈つきで commit し、
+     * transaction id か拒否なら null を返す (跨ぎ cut は同じ id で元を clear する)。
+     */
+    commitPaste: (edits: readonly CellEdit[], sheet: PasteSheet) => number | null
+    maxOperationCells: number
+    onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    onCopyMultiRange?: () => void
+    /** Stable repaint indirection for the marquee sync (§6.5.4-4). / マーキー同期用の安定間接。 */
+    repaintOverlay: () => void
+    /** Drag-freeze probe — clipboard ops consume + no-op mid-drag (mirrors the keydown freeze). / ドラッグ凍結プローブ。 */
+    isDragging: () => boolean
+    /** Track sizes (v0.8): absent ⇒ copies carry no sizes and pastes never resize. / トラック寸法 (v0.8): 不在なら copy は寸法を運ばず paste は寸法を書かない。 */
+    resize?: ClipboardResizeSeam
+    /** Ctrl+Shift+V arms `{ mode: "values" }` here; the next paste event consumes it once. Absent ⇒ every paste is `all`. / Ctrl+Shift+V がここへ `{ mode: "values" }` を武装し、次の paste イベントが 1 回で消費。不在なら常に `all`。 */
+    pendingPasteOptionsRef?: RefObject<PasteOptions | null>
+    /** The host's declared currency / locale for foreign number formats (§1.9 `formats`). / 外来数値書式の解釈に使う宣言通貨 / locale (§1.9 `formats`)。 */
+    formats?: { readonly currency: string; readonly locale?: string }
+    onClipChange?: (clip: ClipInfo | null) => void
+    /** The refusal channel of the read paths — whenever it fires the paste resolves `"rejected"`. / 読み経路の拒否チャネル — 発火した貼り付けは例外なく `"rejected"`。 */
+    onClipboardUnavailable?: (cause: ClipboardUnavailableCause) => void
+    /** Source-side rejection of a cross-sheet cut (the target commit already stands). / 跨ぎ cut の元側拒否 (対象 commit は立っている)。 */
+    onEditRejected?: (error: unknown, rejection: EditRejection) => void
+}
+
+/** The clip surface (§6.5.4-4 — copy/cut unified in v0.3.2, widened in v0.8). / クリップ状態の公開面 (v0.3.2 で copy / cut 統一、v0.8 で拡張)。 */
+export type ClipboardController = {
+    /** The armed clip or null; `foreign` = another adapter's record. / 装填中クリップか null。`foreign` = 別アダプタの記録。 */
+    getClip: () => ClipInfo | null
+    /** Unconditional discard (Escape / edit start / undo-redo — foreign or not). / 無条件破棄 (foreign でも)。 */
+    discardClip: () => void
+    /**
+     * Commit-triggered discard: a `format` / `annotate` commit keeps the clip (Excel keeps the
+     * ants under Ctrl+B), a COPY survives this hook's own paste commit, every other successful
+     * commit discards both kinds. Without a source (v0.7 root) only the own-paste rule applies.
+     * commit 起点の破棄: `format` / `annotate` の commit はクリップを保つ (Excel は Ctrl+B でアンツ
+     * 存続)、copy は自フックの paste commit を生き延び、他の成功 commit は両種とも破棄。source なし
+     * (v0.7 ルート) は自 paste 規則のみ。
+     */
+    discardClipOnCommit: (source?: EditSource) => void
+    /** Adapter switch: discard a COPY record, keep a CUT record (cross-sheet move). / 切替: copy 破棄、cut 保持 (跨ぎ move)。 */
+    onAdapterSwitch: () => void
+    /** Menu path (`navigator.clipboard`) — `handle.paste`. / メニュー経路 — `handle.paste`。 */
+    paste: (options: PasteOptions) => Promise<PasteOutcome>
+}
+
+/** The flavours the menu path materialises before detection (`getData` must be synchronous). / メニュー経路が検出前に実体化するフレーバー (`getData` は同期でなければならない)。 */
+const MENU_FLAVOURS: readonly string[] = ["text/html", "text/plain"]
+
+/** `Clipboard.read` with the `unsanitized` option the DOM lib does not type yet; `Clipboard` is assignable to it. / DOM lib が未型付けの `unsanitized` オプションつき `Clipboard.read`。`Clipboard` はこれへ代入可能。 */
+type UnsanitizedClipboardReader = { read: (options: { unsanitized: readonly string[] }) => Promise<ClipboardItems> }
+
+/** The one target cursor `patchFromClipCell` reads: coordinates rewritten per visited cell, thunks bound to the cursor. / `patchFromClipCell` が読む唯一のターゲットカーソル: 座標は訪問セル毎に書き換え、thunk はカーソルに束縛。 */
+type PasteCursor = { row: number; col: number; readonly readText: () => string; readonly readFormat: () => CellFormat | undefined }
+
+/**
+ * Tile-aware paste cell count from DIMENSIONS only (ADR-12 pre-check for the sources whose
+ * dimensions are known before any cell exists: the `aqsp` header, the HTML estimator, the TSV
+ * counting scan). The `estimatePasteCellCount` table: a non-1×1 target whose both extents are exact
+ * multiples tiles (target area), anything else expands once (source area); no rows or no columns
+ * ⇒ 0.
+ * 寸法だけからのタイル込み貼り付けセル数 (ADR-12 の事前検査 — `aqsp` ヘッダ / HTML 見積もり /
+ * TSV 計数走査のようにセル実体化前に寸法が分かるソース用)。`estimatePasteCellCount` の表:
+ * 1×1 でなく両軸が整数倍のターゲットはタイル (ターゲット面積)、それ以外は 1 回展開 (ソース面積)、
+ * 行なし / 列なしは 0。
+ */
+export const estimateTiledCells = (rows: number, cols: number, target: CellRange): number => {
+    if (rows === 0 || cols === 0) {
+        return 0
+    }
+    const size = rangeSize(target)
+    // 整数倍レンジ (1×1 を除く) はタイル = ターゲット面積、それ以外はソース面積
+    const isTileTarget = !(size.rows === 1 && size.cols === 1) && size.rows % rows === 0 && size.cols % cols === 0
+    return isTileTarget ? size.rows * size.cols : rows * cols
+}
+
+/** True for the plain Ctrl+V options — the only paste that may move a cut (transforms are copy semantics). / 素の Ctrl+V オプションだけ真 — cut を move できる唯一の貼り付け (変換は copy 意味論)。 */
+const isPlainPaste = (options: PasteOptions): boolean => options.mode === "all" && options.operation === undefined && options.transpose !== true && options.skipBlanks !== true
+
+/**
+ * The event channel's flavours: the DataTransfer types and a `getData` memoised per type for the
+ * gesture (a paste event's `getData` re-materialises the string on every call — 91 ms for 15.8 MB).
+ * イベント経路のフレーバー: DataTransfer の types と、ジェスチャ内で種別毎に memo した `getData`
+ * (paste イベントの `getData` は呼ぶ度に文字列を再実体化する — 15.8 MB で 91 ms)。
+ */
+const flavoursOf = (data: DataTransfer): ClipFlavours => {
+    const types = Array.from(data.types)
+    const cache = new Map<string, string>()
+    return {
+        types,
+        getData: (type) => {
+            const hit = cache.get(type)
+            if (hit !== undefined) {
+                return hit
+            }
+            const value = data.getData(type)
+            cache.set(type, value)
+            return value
+        },
+    }
+}
+
+/**
+ * The event's DataTransfer, or null when the event carries none — a synthetic `Event("paste")`
+ * has no `clipboardData` property at all (v0.7's `?.` semantics, one judgment point).
+ * イベントの DataTransfer、無ければ null — 合成 `Event("paste")` は `clipboardData` 自体を持たない
+ * (v0.7 の `?.` と同じ意味論、判定点は 1 つ)。
+ */
+const clipboardDataOf = (event: ClipboardEvent): DataTransfer | null => {
+    const data = event.clipboardData
+    return data === undefined || data === null ? null : data
+}
+
+/** The intersection of two ranges, or null when they do not overlap. / 2 レンジの交差、重ならなければ null。 */
+const intersectRange = (a: CellRange, b: CellRange): CellRange | null => {
+    const startRow = Math.max(a.startRow, b.startRow)
+    const endRow = Math.min(a.endRow, b.endRow)
+    const startCol = Math.max(a.startCol, b.startCol)
+    const endCol = Math.min(a.endCol, b.endCol)
+    return startRow > endRow || startCol > endCol ? null : { startRow, startCol, endRow, endCol }
+}
+
+/**
+ * The conditional-format inputs a copy carries: every rule with a range intersecting the copied
+ * rectangle, each range clipped to the intersection and translated to origin-relative
+ * coordinates; rules without any intersection are omitted, `stopIfTrue` travels only when set.
+ * copy が運ぶ条件付き書式入力: コピー矩形と交差するレンジを持つ全規則、各レンジは交差へ切り詰めて
+ * 原点相対へ平行移動。交差の無い規則は省き、`stopIfTrue` は設定時だけ運ぶ。
+ */
+const clipConditionalFormats = (rules: readonly ConditionalFormatRule[], range: CellRange): ConditionalFormatRuleInput[] => {
+    const inputs: ConditionalFormatRuleInput[] = []
+    for (const rule of rules) {
+        const ranges: CellRange[] = []
+        for (const ruleRange of rule.ranges) {
+            const hit = intersectRange(ruleRange, range)
+            if (hit !== null) {
+                ranges.push({ startRow: hit.startRow - range.startRow, startCol: hit.startCol - range.startCol, endRow: hit.endRow - range.startRow, endCol: hit.endCol - range.startCol })
+            }
+        }
+        // コピー矩形と交差しない規則は運ばない
+        if (ranges.length === 0) {
+            continue
+        }
+        const input: ConditionalFormatRuleInput = { sourceRuleId: rule.id, ranges, condition: rule.condition, style: rule.style }
+        if (rule.stopIfTrue !== undefined) {
+            input.stopIfTrue = rule.stopIfTrue
+        }
+        inputs.push(input)
+    }
+    return inputs
+}
+
+/**
+ * Reads one cell into its wire form: raw text always; then each aspect ONLY when its read is
+ * declared (a capability branch per aspect, never a value substitute) — the formula as
+ * cell-relative R1C1 (`resolveEditText` enforces the leading "="), the format and validation
+ * through the interners (an empty canonical format has no `fmt`), the note, the id-less comment
+ * thread (an empty thread is no thread) and the hyperlink verbatim.
+ * セル 1 つを wire 形へ読む: 素の文字列は常に、各側面は読みが宣言されているときだけ (側面毎の
+ * 能力分岐、値代替はしない) — 数式はセル相対 R1C1 (`resolveEditText` が "=" 始まりを強制)、書式と
+ * 検証は interner 経由 (空の正準書式は `fmt` なし)、ノート、id を剥がしたコメント (空スレッドは
+ * 不在)、ハイパーリンクは原文。
+ */
+const readClipCell = (adapter: SpreadsheetDataAdapter, formats: ClipFormatInterner, validations: ClipValidationInterner, row: number, col: number): ClipCell => {
+    // 数式の能力分岐と "=" の fail-fast は resolveEditText が担う (数式セルだけ getCellText を追加で読む)
+    const edit = resolveEditText(adapter, row, col)
+    const cell: ClipCell = { t: edit.isFormula ? adapter.getCellText(row, col) : edit.text }
+    if (edit.isFormula) {
+        cell.f = toR1C1(edit.text, { row, col })
+    }
+    if (adapter.getCellFormat !== undefined) {
+        const format = adapter.getCellFormat(row, col)
+        if (format !== undefined) {
+            const fmt = formats.intern(format)
+            // 空の正準形は側面なし (辞書にも載らない)
+            if (fmt !== undefined) {
+                cell.fmt = fmt
+            }
+        }
+    }
+    if (adapter.getCellNote !== undefined) {
+        const note = adapter.getCellNote(row, col)
+        if (note !== undefined) {
+            cell.note = note
+        }
+    }
+    if (adapter.getCellComments !== undefined) {
+        const thread = adapter.getCellComments(row, col)
+        // wire は consumer の id を運ばない (貼り付け先では全件新規)
+        if (thread !== undefined && thread.length > 0) {
+            cell.comments = thread.map(({ text, author, createdAt }) => ({ text, author, createdAt }))
+        }
+    }
+    if (adapter.getCellHyperlink !== undefined) {
+        // 信頼境界 (ADR-10): 生のアダプタ URL を許可リストへ正規化 — 正規化不能は側面ごと落とす
+        // (sanitizeLinks と同じ規則)。装填 payload と text/html 書出はこの読みだけを源に持つため、
+        // 許可外スキームはクリップのどのフレーバーにも CellPatch.hyperlink にも決して載らない
+        const link = normalizeAdapterHyperlink(adapter.getCellHyperlink(row, col))
+        if (link !== undefined) {
+            cell.link = link
+        }
+    }
+    if (adapter.getCellValidation !== undefined) {
+        const rule = adapter.getCellValidation(row, col)
+        if (rule !== undefined) {
+            cell.val = validations.intern(rule)
+        }
+    }
+    return cell
+}
+
+/** The cell-content part of a payload (what a paste writes): the dictionaries, the cells and the origin-relative conditional formats. / payload のセル内容部 (貼り付けが書くもの): 辞書、セル、原点相対の条件付き書式。 */
+type ClipContent = Pick<ClipPayload, "formats" | "validations" | "cells" | "conditionalFormats">
+
+/**
+ * Reads the content of `range` from `adapter`: every cell through `readClipCell` with one format
+ * and one validation interner per read, and the intersecting conditional formats origin-relative
+ * (capability branch: only when `getConditionalFormats` is declared).
+ * `adapter` から `range` の内容を読む: 全セルを `readClipCell` で (読み 1 回につき書式 / 検証の
+ * interner 1 つずつ)、交差する条件付き書式は原点相対 (能力分岐: `getConditionalFormats` 宣言時だけ)。
+ */
+const readRangeContent = (adapter: SpreadsheetDataAdapter, range: CellRange): ClipContent => {
+    const formats = createFormatInterner()
+    const validations = createValidationInterner()
+    const cells: ClipCell[][] = []
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const line: ClipCell[] = []
+        for (let col = range.startCol; col <= range.endCol; col += 1) {
+            line.push(readClipCell(adapter, formats, validations, row, col))
+        }
+        cells.push(line)
+    }
+    return {
+        formats: formats.entries,
+        validations: validations.entries,
+        cells,
+        // 能力分岐: 条件付き書式は getConditionalFormats 宣言時だけ運ぶ
+        conditionalFormats: adapter.getConditionalFormats === undefined ? [] : clipConditionalFormats(adapter.getConditionalFormats(), range),
+    }
+}
+
+/**
+ * The payload an armed record pastes on a clip-id hit: a COPY is its snapshot; a CUT re-reads the
+ * range from the SOURCE adapter now (Excel's deferred cut — a format / note / link / validation
+ * written after Ctrl+X moves with the cells, nothing captured at Ctrl+X is silently destroyed)
+ * while keeping the snapshot's clip id, dimensions, whole flags and sizes. The read happens after
+ * the ADR-12 estimate (the dimensions are the snapshot's).
+ * clip id 一致で装填記録が貼る payload: copy は snapshot、cut は**今**元アダプタからレンジを再読
+ * (Excel の遅延 cut — Ctrl+X 後に書いた書式 / ノート / リンク / 検証がセルと共に動き、Ctrl+X 時点
+ * の捕捉が黙って壊されない) し、snapshot の clip id・寸法・whole フラグ・寸法列は保つ。読みは
+ * ADR-12 見積もり (寸法は snapshot のもの) の後。
+ */
+const armedPayload = (record: ClipRecord): ClipPayload => (record.kind === "cut" ? { ...record.payload, ...readRangeContent(record.sourceAdapter, record.range) } : record.payload)
+
+/** A plain TSV matrix as a payload: text-only cells, empty dictionaries, a fresh clip id (never an identity hit). / 素の TSV 行列を payload に: text だけのセル、空辞書、新規 clip id (identity ヒットは起きない)。 */
+const payloadFromTsv = (matrix: readonly (readonly string[])[]): ClipPayload => ({
+    v: 1,
+    rows: matrix.length,
+    cols: matrix[0].length,
+    clipId: newClipId(),
+    formats: [],
+    validations: [],
+    cells: matrix.map((line) => line.map((t) => ({ t }))),
+    wholeRows: false,
+    wholeCols: false,
+    conditionalFormats: [],
+})
+
+/**
+ * Reader-side hyperlink rule for a FOREIGN JSON payload (`parseClipPayload` validates `link`
+ * structurally only): every `link` goes through `normalizeHyperlink`; an unnormalisable link drops
+ * the aspect (the patch contract says a hyperlink patch IS a `normalizeHyperlink` output). The HTML
+ * reader already normalises and an armed payload is normalised at read time (`readClipCell` routes
+ * every adapter link through `normalizeAdapterHyperlink` — ADR-10), so neither is re-scanned.
+ * Copy-on-write: untouched rows and cells keep identity, a payload without any bad link is returned
+ * as is.
+ * 外来 JSON payload の reader 側ハイパーリンク規則 (`parseClipPayload` は `link` を構造だけ検証):
+ * 全 `link` を `normalizeHyperlink` に通し、正規化できないリンクは側面ごと落とす (パッチ契約:
+ * hyperlink パッチは `normalizeHyperlink` の出力)。HTML reader は正規化済み、装填 payload は読み口
+ * (`readClipCell` が全アダプタリンクを `normalizeAdapterHyperlink` へ通す — ADR-10) で正規化済み
+ * なので再走査しない。copy-on-write: 触れない行 / セルは identity、不正リンクの無い payload は
+ * そのまま返す。
+ */
+const sanitizeLinks = (payload: ClipPayload): ClipPayload => {
+    let changed = false
+    const cells: (readonly ClipCell[])[] = []
+    for (const line of payload.cells) {
+        let lineChanged = false
+        const next: ClipCell[] = []
+        for (const cell of line) {
+            if (cell.link === undefined) {
+                next.push(cell)
+                continue
+            }
+            const link = normalizeHyperlink(cell.link)
+            if (link === cell.link) {
+                next.push(cell)
+                continue
+            }
+            lineChanged = true
+            if (link === null) {
+                // 正規化できないリンクは側面ごと落とす (代替 URL は書かない)
+                const { link: _dropped, ...rest } = cell
+                next.push(rest)
+            } else {
+                next.push({ ...cell, link })
+            }
+        }
+        if (lineChanged) {
+            changed = true
+        }
+        cells.push(lineChanged ? next : line)
+    }
+    return changed ? { ...payload, cells } : payload
+}
+
+/**
+ * The cut-move clear patch of one source cell: `text: ""` plus a null for every aspect the SOURCE
+ * adapter declares (a v0.7 adapter gets exactly `{ row, col, text: "" }`).
+ * cut-move の元セル 1 つの clear パッチ: `text: ""` と、元アダプタが宣言する側面それぞれの null
+ * (v0.7 アダプタは正確に `{ row, col, text: "" }`)。
+ */
+const clearPatch = (row: number, col: number, caps: AspectCapabilities): CellEdit => {
+    const edit: CellEdit = { row, col, text: "" }
+    if (caps.format) {
+        edit.format = null
+    }
+    if (caps.note) {
+        edit.note = null
+    }
+    if (caps.comments) {
+        edit.comments = null
+    }
+    if (caps.hyperlink) {
+        edit.hyperlink = null
+    }
+    if (caps.validation) {
+        edit.validation = null
+    }
+    return edit
+}
+
+/**
+ * The rectangle a paste occupies: from the first (top-left) tile origin to the farthest tile's
+ * far corner, clamped to the grid (the v0.7 "actual written rectangle" — identical to the min /
+ * max over the edits when every cell is written, and still defined for a CF-only or skip-blanks
+ * paste). Null when no tile entered the grid.
+ * 貼り付けが占める矩形: 先頭 (左上) タイル原点から最遠タイルの端まで、グリッドへクランプ (v0.7 の
+ * 「実書込矩形」 — 全セルを書くときは edits の min / max と同一で、CF だけ / skipBlanks の貼り付け
+ * でも定義される)。グリッドに入ったタイルが無ければ null。
+ */
+const pasteRect = (tiles: readonly CellCoord[], rows: number, cols: number, rowCount: number, colCount: number): CellRange | null => {
+    if (tiles.length === 0) {
+        return null
+    }
+    let endRow = 0
+    let endCol = 0
+    for (const tile of tiles) {
+        endRow = Math.max(endRow, tile.row + rows - 1)
+        endCol = Math.max(endCol, tile.col + cols - 1)
+    }
+    return makeRange({ row: tiles[0].row, col: tiles[0].col }, { row: Math.min(endRow, rowCount - 1), col: Math.min(endCol, colCount - 1) })
+}
+
+/**
+ * Wires clipboard events to the sink and owns the armed clip (copy/cut marquee + cut-move + the
+ * menu paste path).
+ * クリップボードイベントをシンクへ結線し、装填中クリップ (copy / cut マーキー + cut-move +
+ * メニュー貼り付け経路) を所有する。
+ */
+export const useClipboard = (params: UseClipboardParams): ClipboardController => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    /** The armed clip (ref — changing it never re-renders §6.5.4-4). / 装填中クリップ (ref — 変更で再レンダーしない §6.5.4-4)。 */
+    const clipRef = useRef<ClipRecord | null>(null)
+
+    /**
+     * Which paste of THIS hook is inside the commit seam: `"own"` = the armed payload itself
+     * (clip-id identity hit — the clip survives whatever its kind), `"foreign"` = any other source
+     * (a copy survives, a cut is consumed — v0.7 rule), `"none"` outside the seam.
+     * 自フックのどの paste が commit シーム中か: `"own"` = 装填 payload そのもの (clip id 一致 —
+     * 種別を問わずクリップ存続)、`"foreign"` = 他ソース (copy は存続、cut は消費 — v0.7 規則)、
+     * `"none"` = シーム外。
+     */
+    const pasteInFlightRef = useRef<"none" | "own" | "foreign">("none")
+
+    /**
+     * Discards the clip, erases the marquee synchronously and notifies (idempotent — no-op when clear).
+     * クリップを破棄しマーキーを同期消去して通知する (冪等 — 無ければ no-op)。
+     */
+    const discardClip = useCallback(() => {
+        if (clipRef.current === null) {
+            return
+        }
+        clipRef.current = null
+        // マーキーの同期消去 (§6.5.4-4 — repaintOverlay が getClip を命令読みして描く)
+        paramsRef.current.repaintOverlay()
+        paramsRef.current.onClipChange?.(null)
+    }, [])
+
+    /**
+     * Commit-triggered discard (see ClipboardController.discardClipOnCommit).
+     * commit 起点の破棄 (ClipboardController.discardClipOnCommit 参照)。
+     */
+    const discardClipOnCommit = useCallback(
+        (source?: EditSource) => {
+            const clip = clipRef.current
+            if (clip === null) {
+                return
+            }
+            // 書式 / 注釈の commit はクリップを保つ (Excel: コピー中の Ctrl+B でアンツは消えない)
+            if (source === "format" || source === "annotate") {
+                return
+            }
+            // 装填 payload 自身の paste は種別を問わず温存 (copy は連続ペースト可、cut の Paste Special は
+            // copy 意味論 — move は別経路で消費済み)。他ソースの paste 中は copy だけ温存 (v0.7 規則)、
+            // 編集 / Delete / fill 等の他 commit は両種とも破棄
+            const inFlight = pasteInFlightRef.current
+            if (inFlight === "own" || (inFlight === "foreign" && clip.kind === "copy")) {
+                return
+            }
+            discardClip()
+        },
+        [discardClip],
+    )
+
+    /**
+     * Adapter switch: a copy record is discarded, a cut record survives for the cross-sheet move
+     * (its marquee hides through `foreign`; the consumer is told the record is now foreign).
+     * アダプタ切替: copy 記録は破棄、cut 記録は跨ぎ move のため保持 (マーキーは `foreign` で非表示、
+     * consumer へは記録が foreign になったと通知)。
+     */
+    const onAdapterSwitch = useCallback(() => {
+        const clip = clipRef.current
+        if (clip === null) {
+            return
+        }
+        if (clip.kind === "copy") {
+            discardClip()
+            return
+        }
+        const p = paramsRef.current
+        p.repaintOverlay()
+        p.onClipChange?.({ kind: "cut", range: clip.range, foreign: clip.sourceAdapter !== p.adapter })
+    }, [discardClip])
+
+    /** Arms a record and notifies (copy / cut success). / 記録を装填して通知する (copy / cut 成功)。 */
+    const armClip = useCallback((kind: "copy" | "cut", range: CellRange, payload: ClipPayload) => {
+        const p = paramsRef.current
+        clipRef.current = { kind, range, clipId: payload.clipId, sourceAdapter: p.adapter, payload }
+        p.repaintOverlay()
+        p.onClipChange?.({ kind, range, foreign: false })
+    }, [])
+
+    /**
+     * Reads the range into a payload: the content through `readRangeContent` (cells, dictionaries,
+     * origin-relative conditional formats), the whole-row / whole-column flags, and — only with the
+     * resize seam — the sizes of a whole-column (widths) / whole-row (heights) copy, each clamped to
+     * MAX_TRACK_SIZE_PX (the writer must never emit a payload the wire validator rejects). A fresh
+     * clip id per copy.
+     * レンジを payload へ読む: 内容は `readRangeContent` (セル、辞書、原点相対の条件付き書式)、全行 /
+     * 全列フラグ、resize シームがあるときだけ全列 copy の幅 / 全行 copy の高さ (各寸法は
+     * MAX_TRACK_SIZE_PX へクランプ — writer は wire 検証器が拒む payload を出さない)。clip id は
+     * copy 毎に採番。
+     */
+    const buildClipPayload = useCallback((range: CellRange): ClipPayload => {
+        const p = paramsRef.current
+        const adapter = p.adapter
+        const size = rangeSize(range)
+        const payload: ClipPayload = {
+            v: 1,
+            rows: size.rows,
+            cols: size.cols,
+            clipId: newClipId(),
+            ...readRangeContent(adapter, range),
+            wholeRows: isWholeRows(range, adapter.colCount),
+            wholeCols: isWholeCols(range, adapter.rowCount),
+        }
+        // 寸法は resize シーム (能力) があり、かつ全列 / 全行の copy のときだけ運ぶ。
+        // 命令 resize API (v0.1 契約) は上限を持たず軸は wire 上限超の寸法を合法に保持し得るため、
+        // 「parser が拒む文字列を出さない」不変量を守るには writer 側で MAX_TRACK_SIZE_PX へ削る
+        if (p.resize !== undefined) {
+            if (payload.wholeCols) {
+                const widths: number[] = []
+                for (let col = range.startCol; col <= range.endCol; col += 1) {
+                    widths.push(Math.min(p.resize.colAxis.sizeOf(col), MAX_TRACK_SIZE_PX))
+                }
+                payload.colWidths = widths
+            }
+            if (payload.wholeRows) {
+                const heights: number[] = []
+                for (let row = range.startRow; row <= range.endRow; row += 1) {
+                    heights.push(Math.min(p.resize.rowAxis.sizeOf(row), MAX_TRACK_SIZE_PX))
+                }
+                payload.rowHeights = heights
+            }
+        }
+        return payload
+    }, [])
+
+    /**
+     * The copy/cut common part (§6.5.4-3): check → read → serialize the three flavours → setData.
+     * Returns the payload and its range on success.
+     * copy / cut の共通部 (§6.5.4-3): 検査 → 読み → 3 フレーバーの直列化 → setData。成功時に
+     * payload とレンジを返す。
+     */
+    const serializeCurrentRange = useCallback(
+        (event: ClipboardEvent, op: "copy" | "cut"): { payload: ClipPayload; range: CellRange } | null => {
+            const p = paramsRef.current
+            const selection = p.getSelection()
+            const range = selection.ranges[selection.ranges.length - 1]
+            // 上限検査が常に先 (ADR-12)
+            const count = countRangeCells([range])
+            if (count > p.maxOperationCells) {
+                event.preventDefault() // 「何もしない」= ネイティブがシンクの " " をコピーするのも防ぐ
+                p.onOperationRejected?.(op, count, "limit")
+                return null
+            }
+            // 複数レンジ選択は末尾レンジのみ + 通知 (明示逸脱 — Excel の整列連結コピーは非対応 §6.5.4-3)
+            if (selection.ranges.length > 1) {
+                p.onCopyMultiRange?.()
+            }
+            const payload = buildClipPayload(range)
+            const json = serializeClipPayload(payload)
+            const data = clipboardDataOf(event)
+            if (data !== null) {
+                // TSV は素の文字列 (数式セルも値文字列)、HTML は先頭属性に同じ JSON、カスタム MIME は
+                // paste イベント経路の高速マーカー (read() 経路には届かない)
+                data.setData("text/plain", serializeTsv(payload.cells.map((line) => line.map((cell) => cell.t))))
+                data.setData("text/html", serializeHtmlTable(payload, json))
+                data.setData(CLIP_MIME, json)
+            }
+            event.preventDefault()
+            return { payload, range }
+        },
+        [buildClipPayload],
+    )
+
+    /**
+     * Commits ONE paste transaction through the commit seam (sheet context, transaction id) and
+     * returns whether the adapter accepted (the id itself is only needed by the cross-sheet cut).
+     * 貼り付け 1 トランザクションを commit シーム (シート文脈、transaction id) で commit し、アダプタが
+     * 受理したかを返す (id 自体は跨ぎ cut だけが使う)。
+     */
+    const commitPasteEdits = useCallback((edits: readonly CellEdit[], sheet: PasteSheet): boolean => paramsRef.current.commitPaste(edits, sheet) !== null, [])
+
+    /**
+     * Writes the sizes a paste carries (mode with `sizes`, resize seam present, payload sizes
+     * present): one gated `resizeTracks` batch per axis over the paste rectangle, the payload's
+     * pattern repeated per tile; a gate refusal reports `onOperationRejected("resize", …)`.
+     * 貼り付けが運ぶ寸法を書く (`sizes` を持つモード、resize シームあり、payload に寸法あり):
+     * 貼り付け矩形の軸毎にゲート済み `resizeTracks` 1 バッチ、payload のパターンをタイル毎に反復。
+     * ゲート拒否は `onOperationRejected("resize", …)`。
+     */
+    const applyPasteSizes = useCallback((payload: ClipPayload, rect: CellRange, aspects: PasteAspects) => {
+        const p = paramsRef.current
+        if (!aspects.sizes || p.resize === undefined) {
+            return
+        }
+        const { rowAxis, colAxis, resizeTracks } = p.resize
+        const gate = (axisKind: "row" | "col", axis: AxisModel, entries: readonly ResizeEntry[]) => {
+            const result = gateResizeEntries(axis, entries, null, { maxOperationCells: p.maxOperationCells, rowHiddenLimit: ROW_HIDDEN_LIMIT, axisKind })
+            if (!result.ok) {
+                p.onOperationRejected?.("resize", result.count, result.reason)
+                return
+            }
+            resizeTracks(axisKind, result.entries)
+        }
+        if (payload.colWidths !== undefined) {
+            const entries: ResizeEntry[] = []
+            for (let col = rect.startCol; col <= rect.endCol; col += 1) {
+                entries.push({ index: col, size: payload.colWidths[(col - rect.startCol) % payload.cols] })
+            }
+            gate("col", colAxis, entries)
+        }
+        if (payload.rowHeights !== undefined) {
+            const entries: ResizeEntry[] = []
+            for (let row = rect.startRow; row <= rect.endRow; row += 1) {
+                entries.push({ index: row, size: payload.rowHeights[(row - rect.startRow) % payload.rows] })
+            }
+            gate("row", rowAxis, entries)
+        }
+    }, [])
+
+    /**
+     * The non-tiling cut-move of the armed CUT record (a plain paste with a clip-id hit): estimate
+     * = source area + clear count (never the tile formula), bounds refusal when the block would
+     * leave the grid OR when the armed source range no longer fits the source adapter's CURRENT
+     * extents (rows / columns deleted after Ctrl+X — the deferred read and the clears must never
+     * touch outside the grid), then the DEFERRED read of the source range (`armedPayload` — the
+     * cells as they are now), clears (full-null of the SOURCE adapter's aspects) then writes.
+     * Formulas move VERBATIM (Excel / Sheets: a move never re-anchors relative references — each
+     * cell's R1C1 form is resolved at its SOURCE coordinate, a round-trip identity). Same
+     * sheet: ONE transaction (overlap resolves clear → write, §6.2.3). Another sheet: the target
+     * commit first (translated conditional formats travel), then the source clears under the same
+     * transaction id; a source throw is reported through `onEditRejected` while the target stands.
+     * 装填 CUT 記録のタイルしない cut-move (clip id 一致の素の貼り付け): 見積もり = ソース面積 +
+     * clear 数 (タイル式ではない)、ブロックがグリッドを出るか、装填後の行 / 列削除で元レンジが元
+     * アダプタの**今の**軸から外れているなら bounds 拒否 (遅延読みと clear はグリッド外に触れない)、
+     * 次に元レンジの**遅延読み** (`armedPayload` — 今のセル)、clear (元アダプタの側面の全 null) →
+     * 書込。数式は**原文のまま**動く (Excel / Sheets: move は相対参照を再アンカーしない — 各セルの
+     * R1C1 を元座標で解決する往復恒等)。同一シート: 1 トランザクション (重なりは clear → 書込の後勝ち、§6.2.3)。跨ぎ: 対象
+     * commit が先 (翻訳した条件付き書式を同伴)、次に同一 transaction id で元 clear。元の throw は
+     * `onEditRejected` へ通知し対象は立つ。
+     */
+    const runCutMove = useCallback(
+        (armed: ClipRecord, target: CellRange): PasteOutcome => {
+            const p = paramsRef.current
+            const adapter = p.adapter
+            const snapshot = armed.payload
+            const origin: CellCoord = { row: target.startRow, col: target.startCol }
+            // cut 経路の上限見積もりはタイルでなくソース寸法 + clear ぶん (§6.5.4-4 — タイル前提の
+            // 見積もりは過大で正当な move を誤拒否する)。寸法は snapshot のもの (読みは後)
+            const cellCount = snapshot.rows * snapshot.cols + countRangeCells([armed.range])
+            if (cellCount > p.maxOperationCells) {
+                p.onOperationRejected?.("paste", cellCount, "limit")
+                return "rejected" // クリップは維持
+            }
+            // cut の貼り付けはタイリングしない (Excel 準拠)。クリップ発生 = 拒否 (§6.5.4-4 —
+            // 許すと「はみ出したセルは clear だけされて書かれない」静かなデータ喪失)
+            if (origin.row + snapshot.rows > adapter.rowCount || origin.col + snapshot.cols > adapter.colCount) {
+                p.onOperationRejected?.("paste", cellCount, "bounds")
+                return "rejected" // クリップは維持 — consumer は「シート端を超えて貼り付けできません」を出せる
+            }
+            // 元レンジの staleness 検査: Ctrl+X 後の行 / 列削除で元レンジが今の軸から外れ得る。遅延読みと
+            // clear がグリッド外へ触れる前に文書化済みの bounds 規則で拒否する (トランザクション途中の
+            // throw / 範囲外 clear の送出にはしない — クリップは維持)
+            if (armed.range.endRow >= armed.sourceAdapter.rowCount || armed.range.endCol >= armed.sourceAdapter.colCount) {
+                p.onOperationRejected?.("paste", cellCount, "bounds")
+                return "rejected"
+            }
+            // 遅延読み: Ctrl+X 後の書式 / 注釈 commit を運ぶ (ゲートは snapshot 寸法で済んでいる)
+            const payload = armedPayload(armed)
+            const caps = aspectCapabilities(adapter)
+            const shaped = stripUndeclaredAspects(payload, caps)
+            const cursor: PasteCursor = {
+                row: 0,
+                col: 0,
+                readText: () => resolveEditText(adapter, cursor.row, cursor.col).text,
+                readFormat: () => (adapter.getCellFormat === undefined ? undefined : adapter.getCellFormat(cursor.row, cursor.col)),
+            }
+            // 1×1 ターゲット = 原点から 1 回だけ展開 (境界は上で検査済みなので切り捨ては起きない)。
+            // move は数式を原文のまま運ぶ (Excel / Sheets: cut-paste は相対参照を再アンカーしない) —
+            // R1C1 の解決座標を移動先でなく元セルへ置けば toR1C1 → fromR1C1 が恒等になり原文が動く。
+            // cursor の thunk (readText / readFormat) は素の all モード (演算 / 注入なし) では呼ばれない
+            const { edits: moves, tiles } = expandRichPaste(shaped.cells, makeRange(origin, origin), origin, adapter.rowCount, adapter.colCount, (cell, row, col) => {
+                cursor.row = armed.range.startRow + (row - origin.row)
+                cursor.col = armed.range.startCol + (col - origin.col)
+                return patchFromClipCell(cell, shaped, cursor, DEFAULT_PASTE_OPTIONS, caps)
+            })
+            // clear は元アダプタが宣言する側面の全 null (v0.7 アダプタは text: "" だけ)
+            const sourceCaps = aspectCapabilities(armed.sourceAdapter)
+            const clears: CellEdit[] = []
+            enumerateRangeCells([armed.range], (cell) => {
+                clears.push(clearPatch(cell.row, cell.col, sourceCaps))
+            })
+            if (armed.sourceAdapter === adapter) {
+                // 同一シート: clear → 書込の順に積む (重なりは後勝ち = §6.2.3 の契約)。同一トランザクション
+                if (!commitPasteEdits([...clears, ...moves], { sameSheet: true, conditionalFormats: [] })) {
+                    return "rejected" // 失敗時はクリップも選択も不変 (ラッパーは成功時のみ discard する)
+                }
+            } else {
+                // 跨ぎ: 対象への書込が先 (CF は翻訳して同伴)、成功したら元シートを同一 transaction id で clear。
+                // 元の規則は動かさない (逸脱行)
+                const transaction = p.commitPaste(moves, { sameSheet: false, conditionalFormats: translateConditionalFormats(shaped.conditionalFormats, tiles) })
+                if (transaction === null) {
+                    return "rejected"
+                }
+                try {
+                    armed.sourceAdapter.applyEdits(clears, { transaction, source: "paste", sameSheet: false, conditionalFormats: [] })
+                } catch (error) {
+                    // 対象は立っている — 元側の拒否だけを通知する
+                    p.onEditRejected?.(error, { source: "paste" })
+                }
+            }
+            // 選択を移動先の単一矩形へ (active = anchor = 原点)。rearm はラッパー第 5 段が担う
+            p.setSelection({ ranges: [makeRange(origin, { row: origin.row + payload.rows - 1, col: origin.col + payload.cols - 1 })], anchor: origin, active: origin })
+            return "applied"
+        },
+        [commitPasteEdits],
+    )
+
+    /**
+     * The one paste pipeline of both channels: detect → estimate before materialising (ADR-12) →
+     * read the ONE detected source (clip-id identity reuses the armed payload; a cut hit under a
+     * plain paste is the cut-move) → transpose / strip undeclared aspects → tile through
+     * `expandRichPaste` with `patchFromClipCell` → conditional formats per tile (tiles × rule
+     * ranges gated by the same cap BEFORE materialising — the CF write channel is independent of
+     * the cell count) → commit (an empty
+     * transaction never reaches the adapter) → sizes → selection to the paste rectangle.
+     * 両経路共通の貼り付け経路: 検出 → 実体化前の見積もり (ADR-12) → 検出した唯一のソースを読む
+     * (clip id 一致は装填 payload を再利用、素の貼り付けでの cut 一致は cut-move) → 転置 / 未宣言側面の
+     * 除去 → `expandRichPaste` + `patchFromClipCell` でタイル → タイル毎の条件付き書式 (タイル数 ×
+     * レンジ数を実体化**前**に同じ上限で門番 — CF 書込チャネルはセル数と独立) → commit (空
+     * トランザクションはアダプタへ届かない) → 寸法 → 選択を貼り付け矩形へ。
+     */
+    const runPaste = useCallback(
+        (flavours: ClipFlavours, channel: ClipChannel, options: PasteOptions): PasteOutcome => {
+            const p = paramsRef.current
+            const adapter = p.adapter
+            /** Fires the refusal channel and resolves the paste as rejected. / 拒否チャネルを鳴らし貼り付けを rejected で終える。 */
+            const unavailable = (cause: ClipboardUnavailableCause): PasteOutcome => {
+                p.onClipboardUnavailable?.(cause)
+                return "rejected"
+            }
+            const source = detectClipSource(flavours, channel)
+            if (source === "none") {
+                // イベント経路は v0.7 と同じ無言 no-op (画像等のみのクリップボード)、メニュー経路は「空」を通知
+                return channel === "menu" ? unavailable("empty") : "empty"
+            }
+            const selection = p.getSelection()
+            const target = selection.ranges[selection.ranges.length - 1]
+            const transpose = options.transpose === true
+            /** ADR-12 gate on dimensions (transposed shape when transposing). / 寸法での ADR-12 ゲート (転置時は転置後の形)。 */
+            const overLimit = (rows: number, cols: number): boolean => {
+                const estimate = estimateTiledCells(transpose ? cols : rows, transpose ? rows : cols, target)
+                if (estimate > p.maxOperationCells) {
+                    p.onOperationRejected?.("paste", estimate, "limit")
+                    return true
+                }
+                return false
+            }
+            let payload: ClipPayload
+            /** The armed record when the source IS the armed payload (clip-id identity hit). / ソースが装填 payload そのもの (clip id 一致) のときの装填記録。 */
+            let own: ClipRecord | null = null
+            if (source === "aqsp") {
+                // ヘッダだけを読む (本文 parse なし): 同一性判定と見積もりの両方がここで済む
+                const header = readClipSourceHeader(flavours, channel)
+                if (header === null) {
+                    return unavailable("unreadable")
+                }
+                const pending = clipRef.current
+                if (pending !== null && header.clipId === pending.clipId) {
+                    own = pending
+                }
+                // cut-move は clip id 同一性 + 素の貼り付けだけ (paste special の cut は copy 意味論)
+                if (own !== null && own.kind === "cut" && isPlainPaste(options)) {
+                    return runCutMove(own, target)
+                }
+                if (overLimit(header.rows, header.cols)) {
+                    return "rejected"
+                }
+                if (own !== null) {
+                    // cut の identity ヒットは元レンジを今から再読する (Paste Special の copy 意味論でも) —
+                    // 装填後の行 / 列削除で元レンジが元アダプタの今の軸から外れていたら、再読が範囲外へ
+                    // 触れる前に文書化済みの bounds 規則で拒否する (runCutMove の staleness 検査と対)
+                    if (own.kind === "cut" && (own.range.endRow >= own.sourceAdapter.rowCount || own.range.endCol >= own.sourceAdapter.colCount)) {
+                        p.onOperationRejected?.("paste", own.payload.rows * own.payload.cols, "bounds")
+                        return "rejected"
+                    }
+                    // identity ヒット: parse しない — copy は snapshot、cut は元レンジの遅延読み (copy 意味論の Paste Special でも今のセル)
+                    payload = armedPayload(own)
+                } else {
+                    const parsed = readClipPayload(flavours, channel)
+                    if (parsed === null) {
+                        return unavailable("unreadable")
+                    }
+                    // 実寸をタイル込みで再ゲート (html 経路と対称の第 2 の壁): ヘッダは先頭 512 code unit の
+                    // 正規表現読みで本文と独立 — 重複キー等で寸法を過小申告した敵対 payload が JSON.parse 側
+                    // では実寸を持ち、ヘッダゲートだけだと maxOperationCells を素通りする
+                    if (overLimit(parsed.rows, parsed.cols)) {
+                        return "rejected"
+                    }
+                    // 外来 JSON のリンクだけは信頼しない (HTML reader は正規化済み、装填 payload は自アダプタ由来)
+                    payload = sanitizeLinks(parsed)
+                }
+            } else if (source === "tsv") {
+                const text = flavours.getData("text/plain")
+                // 寸法は同一文法の計数走査 (measureTsv) で実体化前に得る (ADR-12 — html 経路の見積もりと
+                // 対称の壁): 改行だけの巨大クリップボードは行列の実体化 (入力 1 byte あたり数百 byte) が
+                // 拒否より先に OOM するため、parseTsv はゲート通過後にだけ呼ぶ (走査は parse と同じ
+                // scanTsv 文法 — 寸法は常に一致し、quoted 内の埋め込み改行も行と数えない)
+                const dims = measureTsv(text)
+                if (overLimit(dims.rows, dims.cols)) {
+                    return "rejected"
+                }
+                payload = payloadFromTsv(parseTsv(text))
+            } else {
+                // sheets / excel / html: 見積もりは 1 パスの上限値、DOMParser は上限内でしか構築しない
+                const html = flavours.getData("text/html")
+                const estimated = estimateHtmlTableCells(html)
+                // セル未出現の見積もり (cols = 0) は面積 0 でタイルゲートを素通りするが、DOM 構築と行走査は
+                // O(行数) — 行数だけで上限を超える表は reader も (r + 1) × max(cols, 1) の下界で必ず limit に
+                // なるため、DOMParser を建てる前に同じ拒否を返す (ADR-12: DOMParser は上限内でしか構築しない)
+                if (estimated.cols === 0 && estimated.rows > p.maxOperationCells) {
+                    p.onOperationRejected?.("paste", estimated.rows, "limit")
+                    return "rejected"
+                }
+                if (overLimit(estimated.rows, estimated.cols)) {
+                    return "rejected"
+                }
+                // 能力分岐: 宣言通貨 / locale は formats 宣言時だけ渡す。reader 自身も上限で止まる (見積もりが
+                // 見ないもの — 属性値の実体参照等 — に対する ADR-12 の第 2 の壁)
+                const read = parseHtmlTable(html, source, p.formats === undefined ? {} : { currency: p.formats.currency, locale: p.formats.locale }, p.maxOperationCells)
+                if (read.outcome === "none") {
+                    return unavailable("unreadable")
+                }
+                if (read.outcome === "limit") {
+                    p.onOperationRejected?.("paste", read.cells, "limit")
+                    return "rejected"
+                }
+                // 実寸をタイル込みで再ゲート (見積もりより広い実表はタイル数を変え得る)
+                if (overLimit(read.payload.rows, read.payload.cols)) {
+                    return "rejected"
+                }
+                payload = read.payload
+            }
+            const caps = aspectCapabilities(adapter)
+            const shaped = stripUndeclaredAspects(transpose ? transposePayload(payload) : payload, caps)
+            const aspects = MODE_ASPECTS[options.mode]
+            const cursor: PasteCursor = {
+                row: 0,
+                col: 0,
+                readText: () => resolveEditText(adapter, cursor.row, cursor.col).text,
+                readFormat: () => (adapter.getCellFormat === undefined ? undefined : adapter.getCellFormat(cursor.row, cursor.col)),
+            }
+            const { edits, tiles } = expandRichPaste(shaped.cells, target, selection.active, adapter.rowCount, adapter.colCount, (cell, row, col) => {
+                cursor.row = row
+                cursor.col = col
+                return patchFromClipCell(cell, shaped, cursor, options, caps)
+            })
+            const rect = pasteRect(tiles, shaped.rows, shaped.cols, adapter.rowCount, adapter.colCount)
+            if (rect === null) {
+                return "empty" // 全クリップ (原点自体がグリッド外) — 書き込みゼロなら選択も動かさない (v0.7 と同じ無言)
+            }
+            // CF は「タイル数 × 規則のレンジ数」で実体化する第 2 の書込チャネル (セル数ゲートと独立) —
+            // 外来 payload の規則洪水やタイル倍加が maxOperationCells を素通りしないよう、平行移動の
+            // 実体化前に同じ上限で門番する (未宣言 CF は stripUndeclaredAspects が空にしている)
+            if (aspects.cf && shaped.conditionalFormats.length > 0) {
+                let ruleRanges = 0
+                for (const rule of shaped.conditionalFormats) {
+                    ruleRanges += rule.ranges.length
+                }
+                const cfCount = tiles.length * ruleRanges
+                if (cfCount > p.maxOperationCells) {
+                    p.onOperationRejected?.("paste", cfCount, "limit")
+                    return "rejected"
+                }
+            }
+            const conditionalFormats = aspects.cf ? translateConditionalFormats(shaped.conditionalFormats, tiles) : []
+            if (edits.length === 0 && conditionalFormats.length === 0) {
+                // 書き込みゼロ (全セル skip / セル側面のないモード) — 空トランザクションはアダプタへ届けず選択も
+                // 動かさない。寸法 (非 undo 幾何) だけは書く
+                applyPasteSizes(shaped, rect, aspects)
+                return "empty"
+            }
+            // クリップの存続判定 (discardClipOnCommit): 装填 payload 自身の paste は種別を問わず温存、他ソースの
+            // paste は copy だけ温存 (v0.7 規則)。sameSheet = 装填 payload が現アダプタ由来
+            pasteInFlightRef.current = own === null ? "foreign" : "own"
+            let committed = false
+            try {
+                committed = commitPasteEdits(edits, { sameSheet: own !== null && own.sourceAdapter === adapter, conditionalFormats })
+            } finally {
+                pasteInFlightRef.current = "none"
+            }
+            if (!committed) {
+                return "rejected"
+            }
+            applyPasteSizes(shaped, rect, aspects)
+            // 選択は実書込範囲の単一矩形 (名目 outRows × outCols でなく切り捨て後 — §6.5.4-5)
+            const origin: CellCoord = { row: rect.startRow, col: rect.startCol }
+            p.setSelection({ ranges: [rect], anchor: origin, active: origin })
+            return "applied"
+        },
+        [runCutMove, commitPasteEdits, applyPasteSizes],
+    )
+
+    /**
+     * Menu path: one `read({ unsanitized: ["text/html"] })`, the present `text/html` / `text/plain`
+     * blobs materialised BEFORE detection (the flavour reader must be synchronous), then the common
+     * pipeline. Every refusal of the read itself — including a `getType()` / `Blob.text()`
+     * rejection during flavour materialisation (`"unreadable"`) — fires `onClipboardUnavailable`
+     * and resolves `"rejected"` (the promise never rejects); the event-path freeze / editing /
+     * disabled gates apply at write time.
+     * メニュー経路: `read({ unsanitized: ["text/html"] })` 1 回、在る `text/html` / `text/plain` の
+     * Blob を検出前に実体化 (フレーバー読みは同期でなければならない)、以後は共通経路。読み自体の
+     * 拒否は全て — フレーバー実体化中の `getType()` / `Blob.text()` の拒否 (`"unreadable"`) も含め —
+     * `onClipboardUnavailable` を鳴らして `"rejected"` (promise は決して reject しない)。イベント
+     * 経路の凍結 / 編集中 / 無効ゲートは書込時点で適用。
+     */
+    const paste = useCallback(
+        async (options: PasteOptions): Promise<PasteOutcome> => {
+            const unavailable = (cause: ClipboardUnavailableCause): PasteOutcome => {
+                paramsRef.current.onClipboardUnavailable?.(cause)
+                return "rejected"
+            }
+            // 非セキュアオリジン / 非対応環境では navigator.clipboard が無い
+            const clipboardHost: { clipboard?: UnsanitizedClipboardReader } = navigator
+            if (clipboardHost.clipboard === undefined) {
+                return unavailable("insecure-origin")
+            }
+            let items: ClipboardItems
+            try {
+                items = await clipboardHost.clipboard.read({ unsanitized: ["text/html"] })
+            } catch {
+                return unavailable("permission-denied")
+            }
+            if (items.length === 0) {
+                return unavailable("empty")
+            }
+            const item = items[0]
+            const types = Array.from(item.types)
+            const texts = new Map<string, string>()
+            // 非同期 read と Blob 実体化の間にクリップボードが差し替わると getType / text() は拒否で終わる —
+            // 実体化の失敗も「読み自体の拒否」なので unreadable として解決する (try の外だと paste() 自体が
+            // reject し、呼び手の void 呼びで unhandledrejection になる)
+            try {
+                for (const type of MENU_FLAVOURS) {
+                    if (types.includes(type)) {
+                        texts.set(type, await (await item.getType(type)).text())
+                    }
+                }
+            } catch {
+                return unavailable("unreadable")
+            }
+            const flavours: ClipFlavours = {
+                types,
+                getData: (type) => {
+                    const text = texts.get(type)
+                    // 検出は実体化済みフレーバーにしか触れない — それ以外の要求は経路のバグ
+                    if (text === undefined) {
+                        throw new RangeError(`[spreadsheet] clipboard flavour ${type} was not materialised for the menu path`)
+                    }
+                    return text
+                },
+            }
+            // 非同期読みの間に状態は変わり得る — 書込時点でイベント経路と同じゲートを見る
+            const p = paramsRef.current
+            if (!p.enabled || p.isDragging() || p.isEditing()) {
+                return "rejected"
+            }
+            return runPaste(flavours, "menu", options)
+        },
+        [runPaste],
+    )
+
+    const { enabled, sinkRef } = params
+    useEffect(() => {
+        const sink = sinkRef.current
+        if (!enabled || sink === null) {
+            return
+        }
+
+        // ドラッグ凍結 (keydown 面の consume と対称): メニュー / AT 経由の clipboard 操作が飛行中
+        // ドラッグの選択や adapter を変異させない。preventDefault で ネイティブ動作 (シンクの " "
+        // コピー / 巨大テキスト挿入) も遮断する
+        const consumeIfDragging = (event: ClipboardEvent): boolean => {
+            if (paramsRef.current.isDragging()) {
+                event.preventDefault()
+                return true
+            }
+            return false
+        }
+
+        const onCopy = (event: ClipboardEvent) => {
+            const p = paramsRef.current
+            if (consumeIfDragging(event)) {
+                return
+            }
+            if (p.isEditing()) {
+                return // 編集中は textarea ネイティブへ (§6.5.4-1)
+            }
+            const result = serializeCurrentRange(event, "copy")
+            if (result !== null) {
+                // 成功 copy はアンツを装填し直す (v0.3.2 — Excel / Sheets の copy マーキー)。旧 cut
+                // クリップの置換も兼ねる (§6.5.4-4 — 置換しないと cut → Ctrl+C → Ctrl+V の clip id が
+                // 一致して「コピーのつもりが move (元セル clear)」の静かなデータ喪失)。拒否 (null) 時は
+                // 何も起きていないので既存クリップ維持
+                armClip("copy", result.range, result.payload)
+            }
+        }
+
+        const onCut = (event: ClipboardEvent) => {
+            const p = paramsRef.current
+            if (consumeIfDragging(event)) {
+                return
+            }
+            if (p.isEditing()) {
+                return
+            }
+            const result = serializeCurrentRange(event, "cut")
+            if (result === null) {
+                return
+            }
+            // 次の copy / cut は破棄条件 (§6.5.4-4) — 新しい cut クリップで置き換える
+            armClip("cut", result.range, result.payload)
+        }
+
+        const onPaste = (event: ClipboardEvent) => {
+            const p = paramsRef.current
+            if (consumeIfDragging(event)) {
+                return
+            }
+            if (p.isEditing()) {
+                return
+            }
+            // preventDefault 必須 (§6.5.4-5) — 無いと数 MB の TSV がシンクへネイティブ挿入される
+            event.preventDefault()
+            // 武装済みオプション (Ctrl+Shift+V の values モード) は 1 回で消費。ref 未結線 (能力不在) は素の Ctrl+V
+            let options: PasteOptions = DEFAULT_PASTE_OPTIONS
+            const armedRef = p.pendingPasteOptionsRef
+            if (armedRef !== undefined && armedRef.current !== null) {
+                options = armedRef.current
+                armedRef.current = null
+            }
+            const data = clipboardDataOf(event)
+            // clipboardData の無い paste イベントは読むものが無い (v0.7 の空文字 no-op と同じ)
+            if (data === null) {
+                return
+            }
+            runPaste(flavoursOf(data), "event", options)
+        }
+
+        sink.addEventListener("copy", onCopy)
+        sink.addEventListener("cut", onCut)
+        sink.addEventListener("paste", onPaste)
+        return () => {
+            sink.removeEventListener("copy", onCopy)
+            sink.removeEventListener("cut", onCut)
+            sink.removeEventListener("paste", onPaste)
+        }
+    }, [enabled, sinkRef, serializeCurrentRange, armClip, runPaste])
+
+    return useMemo(
+        () => ({
+            getClip: () => {
+                const clip = clipRef.current
+                return clip === null ? null : { kind: clip.kind, range: clip.range, foreign: clip.sourceAdapter !== paramsRef.current.adapter }
+            },
+            discardClip,
+            discardClipOnCommit,
+            onAdapterSwitch,
+            paste,
+        }),
+        [discardClip, discardClipOnCommit, onAdapterSwitch, paste],
+    )
+}