@aiquants/spreadsheet 0.8.0

package/src/clipboard/htmlInterop.ts

@@ -0,0 +1,1694 @@
+/**
+ * @fileoverview Excel / Google Sheets interoperable HTML table WRITER + READER for the clipboard
+ * `text/html` flavour (v0.8 §4.1.7, ADR-14; replaces htmlTable.ts). Pure, React-free, and the
+ * reader is TOTAL fail-soft: any string yields a `ClipPayload` or `null`, never a throw.
+ *
+ * Writer contract (`serializeHtmlTable`, each clause mutation-gated in htmlInterop.spec.ts):
+ * - `<table data-aqsp-clip='…'>` carries the lossless JSON as the FIRST attribute, single-quoted
+ *   with exactly `& < > '` entity-escaped (the closed set `decodeClipAttribute` undoes), so both
+ *   channels of ADR-14 detect `aqsp` on the 16 KiB prefix and `readClipHeader` anchors without
+ *   decoding the body.
+ * - The envelope is the Sheets-origin form (`<google-sheets-html-origin>` + `data-sheets-root="1"`)
+ *   so Google Sheets pastes the typed attributes: `data-sheets-value` (a string for `=` literals and
+ *   text-formatted cells, a number for numeric-formatted numeric text, a date serial for
+ *   date-formatted ISO text), `data-sheets-formula` (the cell-relative R1C1 the payload already
+ *   holds), `data-sheets-numberformat`, `data-sheets-hyperlink`, `data-sheets-note`. Excel reads
+ *   the same cells through `x:str` / `x:num` / `x:fmla` (A1 resolved with the clip at A1;
+ *   off-clip references are omitted rather than shipped as `#REF!`), inline `mso-number-format`
+ *   (Excel's CSS-string escaping, `encodeMsoNumberFormat`), borders in pt with `windowtext` for
+ *   the default colour, `<col width>` / `<tr height>`, and every visible style in the shared CSS
+ *   vocabulary (font-weight / font-style / text-decoration / color / background-color /
+ *   text-align / vertical-align / font-family / font-size pt / border-*). Plain cells stay
+ *   `<td style='white-space:pre'>text</td>` — attributes appear only where an aspect exists.
+ * - The visible text is the DISPLAY string (`formatCellValue`); the typed attributes carry the raw
+ *   value. In-cell newlines are `<br style="mso-data-placement:same-cell">` (plus the `br` rule in
+ *   the `<style>` head), tabs `&#9;`, `& < >` escaped, `white-space:pre` (or `pre-wrap` for wrap
+ *   cells) on every td so HTML whitespace collapsing cannot flatten the text.
+ *
+ * Reader contract (`parseHtmlTable(html, kind, options, maxCells)` ⇒ `HtmlTableResult`):
+ * - Structure comes from `DOMParser` (built by the caller's ADR-12 gate only under the cap); the
+ *   FIRST table in document order is read with the HTML table model: `thead` rows, then `tr` /
+ *   `tbody` rows in tree order, then `tfoot`; `rowspan` / `colspan` expand to the anchor plus
+ *   blank unformatted cells; ragged rows are right-padded. No table, or a table without any cell
+ *   column ⇒ `{ outcome: "none" }`.
+ * - The reader is the SECOND wall of ADR-12: `maxCells` (a positive integer — anything else is a
+ *   RangeError before the DOMParser is built) bounds what it materialises. Before every
+ *   allocation it checks the lower bound `(rows so far) × max(cols so far, width)` of the final
+ *   `rows × cols`; once that exceeds `maxCells` it stops with `{ outcome: "limit", cells }`
+ *   (`cells` = that bound), so at most `maxCells` cell objects ever exist (plus the rectangular
+ *   copy). This fences what `estimateHtmlTableCells` cannot see — entity references inside span
+ *   attribute values, tokenizer corner cases — and the `<col span>` list is read only up to the
+ *   cell column count. Rows are pulled lazily through the sibling links (`firstElementChild` /
+ *   `nextElementSibling` — O(1) a step in every DOM, whereas a live `HTMLCollection` index costs
+ *   O(index) in jsdom and made a 65,534-row walk quadratic), so the bound also ends the row walk:
+ *   the rowspan bomb below visits 101 rows, never 65,534.
+ * - CSS is read from RAW text, never the CSSOM (which drops `mso-*`): `<style>` class rules
+ *   (`.xl65`, `td.xl65`, `.font6`) and inline `style` attributes through `tokenizeInlineStyle`
+ *   (quote- and paren-aware, so `\;` inside an `mso-number-format` string does not split).
+ *   Element rules (`td { … }`, `tr`, `col`, `br`) are an application's defaults and never become
+ *   cell formats; the `table` rule supplies `mso-displayed-*-separator` (else
+ *   `DEFAULT_HTML_SEPARATORS`). Precedence: `bgcolor` attribute < class rules in class order <
+ *   inline style < whole-cell run elements (a `b` / `i` / `u` / `s` / `a` / `font` / `span`
+ *   whose text is the entire cell text; partial runs never format the cell; the whole-cell test
+ *   is the O(1)-per-run window check "no non-whitespace outside the run" — equivalent to
+ *   whitespace-normalised text equality — so a hostile cell nesting thousands of run tags around
+ *   a long string never costs O(depth × text length)).
+ * - Vocabulary → `CellFormat`: bold (`bold` / `bolder` / ≥ 600), italic / oblique, underline and
+ *   line-through tokens of `text-decoration(-line)` (tag `u` / `s` add), `color` and
+ *   `background(-color)` through `normalizeColor` (transparent / unknown ⇒ skipped), `text-align`
+ *   left / center / right, `vertical-align` top / middle / bottom, the first non-generic
+ *   `font-family`, `font-size` in pt or px (× 0.75), `white-space` normal / pre-wrap / pre-line ⇒
+ *   wrap, borders from `border` and `border-<side>` (unit-aware width: px 1 / 2 / ≥ 3 and pt
+ *   < 0.75 / < 1.25 / ≥ 1.25 ⇒ thin / medium / thick, the keywords by name, a missing width =
+ *   CSS `medium`; dashed / dotted / double / hairline ⇒ their styles; `none` / `hidden` /
+ *   transparent ⇒ no side; `windowtext` / `currentcolor` ⇒ default colour; an unknown colour ⇒
+ *   side skipped). The `sheets` kind ignores Sheets' own grid-line
+ *   declaration (`1px solid #cccccc`, inlined by a sanitising engine). `align` / `valign`
+ *   attributes are rendering hints (Excel writes `align=right` for numbers) and are ignored.
+ * - Values: `sheets` reads `data-sheets-value` (types 2 string / 3 number / 4 boolean / 5 error,
+ *   object or the 2015 positional array; a number under a date format is a serial converted to
+ *   ISO by pure calendar math — only inside the grammar's serial domain 0000-01-01 .. 9999-12-31,
+ *   the visible text otherwise), `data-sheets-formula` verbatim when `=`-leading,
+ *   `data-sheets-numberformat`, `data-sheets-hyperlink` (the attribute is the carrier when
+ *   present, the first `<a href>` otherwise), `data-sheets-note`; `data-sheets-userformat` /
+ *   `-textstyleruns` are not read (the CSS carries the cell format; the package has no runs).
+ *   `excel` and `html` are the same reader: `x:str` / `x:bool` / `x:err` / `x:num` (a serial under
+ *   a date format becomes ISO inside the same serial domain, the visible text otherwise) /
+ *   `x:fmla` (A1 → cell-relative R1C1 via `toR1C1`), inline or
+ *   class `mso-number-format` (unquoted, `decodeMsoNumberFormat`, then `fromExcelPattern`), the
+ *   first `<a href>`. Without a typed carrier the visible text is the value; under a NUMERIC value
+ *   format it is canonicalised by `numberDisplayToCanonical` with the table's separators
+ *   (`2,728,548` ⇒ `2728548`, `20.5%` ⇒ `0.205`); under General it is kept verbatim. Hyperlinks
+ *   pass `normalizeHyperlink` or are dropped.
+ * - Text: `<br>` is a newline; text nodes follow the cell's `white-space` — collapse (whitespace
+ *   runs ⇒ one space, U+00A0 ⇒ space, each line trimmed, leading / trailing empty lines dropped,
+ *   block elements and nested rows are line boundaries), `pre` / `pre-wrap` verbatim, `pre-line`
+ *   (spaces collapsed, newlines kept); `mso-spacerun:yes` spans, `<rt>` / `<rp>`, scripts,
+ *   styles, images, form controls and comments contribute nothing. Formats are interned through
+ *   `createFormatInterner` (canonical, deduplicated); comments are never produced; column widths
+ *   (`<col width>` px, `width:Npt` × 4 / 3, `display:none` ⇒ 0, `span`) and row heights
+ *   (`height:Npt|px` then the `height` attribute) are emitted only when every column / row is
+ *   covered; the payload gets a fresh `clipId`, empty `validations` / `conditionalFormats` and
+ *   `wholeRows` / `wholeCols` false.
+ *
+ * Excel / Google Sheets 相互運用の HTML 表 writer + reader (v0.8 §4.1.7、ADR-14。htmlTable.ts を
+ * 置換)。純関数・React 非依存、reader は全域 fail-soft (任意の文字列に対し `ClipPayload` か `null`、
+ * throw しない)。writer: `<table data-aqsp-clip='…'>` を先頭属性に単一引用で置き (`& < > '` のみ
+ * 実体化)、Sheets 起源形 (`<google-sheets-html-origin>` + `data-sheets-root="1"`) で
+ * `data-sheets-value` / `-formula` / `-numberformat` / `-hyperlink` / `-note` を、Excel 向けに
+ * `x:str` / `x:num` / `x:fmla` (クリップを A1 に置いた A1 形、クリップ外参照は省略)・インライン
+ * `mso-number-format` (Excel の CSS 文字列エスケープ)・pt 罫線 (既定色は `windowtext`)・
+ * `<col width>` / `<tr height>`・共通 CSS 語彙を出力。素のセルは `<td style='white-space:pre'>` の
+ * まま。可視文字列は表示文字列 (`formatCellValue`)、型付き属性が素の値を運ぶ。改行は
+ * `<br style="mso-data-placement:same-cell">`、タブは `&#9;`。reader: 構造は `DOMParser` (呼び手の
+ * ADR-12 ゲート下でのみ構築) の HTML 表モデル (thead → tr / tbody → tfoot、rowspan / colspan は
+ * anchor + 空白セル、ラグ行は右詰め)。reader 自身が ADR-12 の第 2 の壁: `maxCells` (正整数、他は
+ * DOMParser 構築前に RangeError) が実体化を上限で止め、rows × cols の下界が超えた時点で
+ * `{ outcome: "limit", cells }` を返す (見積もりが見ない属性値の実体参照等を塞ぐ)。行は兄弟リンク
+ * (`firstElementChild` / `nextElementSibling` — live な `HTMLCollection` の添字は jsdom で O(添字)) で遅延列挙し、
+ * 下界超えは行の走査も止める (65,534 行の爆弾でも訪れる行は 101)。CSS は生文字列から (`<style>` のクラス規則 + インライン、要素規則は既定として無視、
+ * `table` 規則の区切り宣言のみ使用)、優先順は bgcolor < クラス < インライン < 全体 run 要素。
+ * 語彙 → `CellFormat` の写像 (罫線幅は単位別、キーワードは同名、幅なしは CSS `medium`)、Sheets の罫線
+ * 既定 (`1px solid #cccccc`) は無視、`align` / `valign`
+ * 属性は描画ヒントとして無視。値: sheets は `data-sheets-*`、excel / html は `x:*` +
+ * `mso-number-format`、型付き運搬体が無ければ可視文字列 (数値書式下は区切り宣言で正準化、General
+ * は原文)。文字列は `white-space` に従う (collapse / pre / pre-line)、`mso-spacerun` / `<rt>` /
+ * script / img 等は寄与しない。書式は `createFormatInterner` で正準 intern、寸法は全列 / 全行が
+ * 揃うときだけ出力、`clipId` は新規採番。
+ */
+
+import { MAX_TRACK_SIZE_PX } from "../header/resizeGates.ts"
+import { normalizeHyperlink } from "../model/cellAnnotations.ts"
+import { type CellAlign, type CellBorder, type CellBorderStyle, type CellBorders, type CellFormat, type CellValueFormat, type CellVerticalAlign, formatCellValue, parseNumber } from "../model/cellFormat.ts"
+import { normalizeColor } from "../model/cellPaint.ts"
+import { fromR1C1, toR1C1 } from "../model/formulaRefs.ts"
+import { CLIP_ATTRIBUTE, type ClipCell, type ClipPayload, createFormatInterner, HTML_COLSPAN_MAX, HTML_ROWSPAN_MAX, newClipId } from "./clipPayload.ts"
+import { decodeMsoNumberFormat, fromExcelPattern, fromSheetsNumberFormat, type NumberFormatDecodeOptions, type NumberSeparators, numberDisplayToCanonical, toExcelPattern } from "./numberFormatCodec.ts"
+
+// ---------------------------------------------------------------------------------------------
+// Vocabulary
+// 語彙
+// ---------------------------------------------------------------------------------------------
+
+/** The table kinds the reader accepts — the marker-detected `ClipSource` values that are HTML tables. / reader が受ける表の種別 — HTML 表であるマーカー検出済み `ClipSource` 値。 */
+export type HtmlTableKind = "sheets" | "excel" | "html"
+
+/** Google Sheets' wrapper element name (the writer emits it, detection matches it). / Google Sheets のラッパー要素名 (writer が出力、検出が照合)。 */
+export const SHEETS_ORIGIN_TAG = "google-sheets-html-origin"
+
+/**
+ * The displayed-number separators assumed when a document declares none (Excel always writes
+ * `mso-displayed-*-separator` on its `table` rule; Sheets and generic HTML never do). A stated
+ * default of the `text/html` channel, not a substitute for a declared value.
+ * 文書が区切りを宣言しないときに仮定する表示数値の区切り (Excel は常に `table` 規則へ書く。Sheets /
+ * 汎用 HTML は書かない)。`text/html` 経路の宣言済み既定であり、宣言値の代替ではない。
+ */
+export const DEFAULT_HTML_SEPARATORS: NumberSeparators = Object.freeze({ group: ",", decimal: "." })
+
+/** Border style → the pt width + line style Excel and Sheets read back. / 罫線種 → Excel / Sheets が読み戻す pt 幅 + 線種。 */
+const BORDER_CSS: Readonly<Record<CellBorderStyle, string>> = Object.freeze({
+    thin: ".5pt solid",
+    medium: "1.0pt solid",
+    thick: "1.5pt solid",
+    dashed: ".5pt dashed",
+    dotted: ".5pt dotted",
+    double: "1.5pt double",
+    hair: ".5pt hairline",
+})
+
+/** Border sides in the emission order. / 罫線の辺 (出力順)。 */
+const BORDER_SIDES: readonly (keyof CellBorders)[] = ["top", "right", "bottom", "left"]
+
+/** CSS border-style keywords the reader understands. / reader が解する CSS の border-style キーワード。 */
+const BORDER_STYLE_KEYWORDS: ReadonlySet<string> = new Set(["solid", "dashed", "dotted", "double", "hairline", "none", "hidden", "groove", "ridge", "inset", "outset"])
+
+/** Colour words meaning "the automatic / default border colour". / 「自動 (既定) の罫線色」を意味する色語。 */
+const DEFAULT_COLOR_WORDS: ReadonlySet<string> = new Set(["windowtext", "currentcolor", "inherit", "initial", "unset"])
+
+/** Generic family keywords that never name a font. / フォント名にならない総称族キーワード。 */
+const GENERIC_FAMILIES: ReadonlySet<string> = new Set(["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded", "math", "emoji", "fangsong", "inherit", "initial", "unset"])
+
+/** Sheets error sub-codes (research map §3.1) → Excel error text. / Sheets のエラー副コード → Excel のエラー文字列。 */
+const SHEETS_ERROR_TEXT: readonly string[] = ["", "#NULL!", "#DIV/0!", "#VALUE!", "#REF!", "#NAME?", "#NUM!", "#N/A", "#ERROR!"]
+
+/** Sheets `NumberFormatType` codes the writer stamps per package value type. / writer がパッケージの値書式型ごとに刻む Sheets の `NumberFormatType` コード。 */
+const SHEETS_NUMBER_FORMAT_CODE: Readonly<Record<"number" | "percent" | "currency" | "scientific", number>> = Object.freeze({ number: 2, percent: 3, currency: 4, scientific: 8 })
+
+/** Elements whose subtree never contributes cell text. / セル文字列に一切寄与しない要素。 */
+const SKIP_TAGS: ReadonlySet<string> = new Set(["script", "style", "template", "noscript", "rt", "rp", "img", "svg", "video", "audio", "picture", "canvas", "iframe", "object", "textarea", "select", "button", "input"])
+
+/** Elements that end a line in collapse mode (block boundaries, nested table rows). / collapse モードで行を区切る要素 (ブロック境界・入れ子表の行)。 */
+const BLOCK_TAGS: ReadonlySet<string> = new Set(["div", "p", "li", "ul", "ol", "dl", "dt", "dd", "h1", "h2", "h3", "h4", "h5", "h6", "blockquote", "pre", "section", "article", "header", "footer", "table", "tr", "hr"])
+
+/** Run elements that may format the WHOLE cell when their text is the entire cell text. / 文字列がセル全体と一致するとき cell を書式付けし得る run 要素。 */
+const RUN_TAGS: ReadonlySet<string> = new Set(["b", "strong", "i", "em", "u", "s", "strike", "del", "a", "font", "span"])
+
+/** `Node.TEXT_NODE`. / テキストノード。 */
+const TEXT_NODE = 3
+
+/** `Node.ELEMENT_NODE`. / 要素ノード。 */
+const ELEMENT_NODE = 1
+
+/** Sheets / Excel serial epoch (1899-12-30) as days since 1970-01-01. / Sheets / Excel シリアルの元期 (1899-12-30) を 1970-01-01 起点の日数で。 */
+const SERIAL_EPOCH_DAYS = -25569
+
+/** Seconds per day. / 1 日の秒数。 */
+const SECONDS_PER_DAY = 86400
+
+/** Lowest serial of the package date grammar: 0000-01-01 (grammar years are 0000-9999). / パッケージ日付文法の最小シリアル (0000-01-01)。 */
+const SERIAL_GRAMMAR_MIN = -693959
+
+/** Highest serial of the package date grammar: 9999-12-31 (Excel's own ceiling). / パッケージ日付文法の最大シリアル (9999-12-31 — Excel 自身の上限)。 */
+const SERIAL_GRAMMAR_MAX = 2958465
+
+/** The non-breaking space (Excel / Chromium layout space, read as a plain space). / ノーブレークスペース (Excel / Chromium のレイアウト空白、素の空白として読む)。 */
+const NBSP = "\u00a0"
+
+// ---------------------------------------------------------------------------------------------
+// Raw CSS tokenizers (CSSOM never consulted)
+// 生 CSS トークナイザ (CSSOM は参照しない)
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Splits a `style` attribute value (or a rule body) into `name → value` declarations: `;` splits
+ * only outside quotes and parentheses (so `mso-number-format:"…\;…"` and `rgb(0, 0, 0)` stay
+ * whole), a backslash inside quotes escapes the next character, names are trimmed + lower-cased,
+ * values trimmed with their quotes kept, empty names / values dropped, a repeated name keeps the
+ * LAST value (CSS order). Total: any string yields a map.
+ * `style` 属性値 (または規則本体) を `name → value` 宣言へ分割: `;` は引用 / 括弧の外だけで区切り
+ * (`mso-number-format:"…\;…"` や `rgb(0, 0, 0)` は保たれる)、引用内の逆斜線は次の文字をエスケープ、
+ * 名前は trim + 小文字化、値は引用符を保って trim、空の名前 / 値は落とし、重複名は後勝ち (CSS 順)。
+ */
+export const tokenizeInlineStyle = (style: string): ReadonlyMap<string, string> => {
+    const out = new Map<string, string>()
+    let start = 0
+    let quote: string | null = null
+    let depth = 0
+    // 1 宣言を name / value へ分け、空のものは捨てる
+    const flush = (end: number): void => {
+        const declaration = style.slice(start, end)
+        const colon = declaration.indexOf(":")
+        if (colon > 0) {
+            const name = declaration.slice(0, colon).trim().toLowerCase()
+            const value = declaration.slice(colon + 1).trim()
+            if (name !== "" && value !== "") {
+                out.set(name, value)
+            }
+        }
+        start = end + 1
+    }
+    for (let i = 0; i < style.length; i += 1) {
+        const c = style[i]
+        if (quote !== null) {
+            // 引用内: エスケープは次の 1 文字を読み飛ばし、同じ引用符で閉じる
+            if (c === "\\") {
+                i += 1
+            } else if (c === quote) {
+                quote = null
+            }
+        } else if (c === '"' || c === "'") {
+            quote = c
+        } else if (c === "(") {
+            depth += 1
+        } else if (c === ")") {
+            depth = depth > 0 ? depth - 1 : 0
+        } else if (c === ";" && depth === 0) {
+            flush(i)
+        }
+    }
+    flush(style.length)
+    return out
+}
+
+/** Removes ONE layer of matching CSS string quotes (`"…"` / `'…'`). / 対応する CSS 文字列引用符を 1 層だけ外す。 */
+const stripCssQuotes = (value: string): string => {
+    const first = value[0]
+    return value.length >= 2 && (first === '"' || first === "'") && value.endsWith(first) ? value.slice(1, -1) : value
+}
+
+/** Whitespace-splits a CSS value without breaking `rgb( … )` style functions. / `rgb( … )` を壊さずに CSS 値を空白分割。 */
+const splitCssTokens = (value: string): string[] => {
+    const tokens: string[] = []
+    let current = ""
+    let depth = 0
+    for (const c of value) {
+        if (c === "(") {
+            depth += 1
+        } else if (c === ")") {
+            depth = depth > 0 ? depth - 1 : 0
+        }
+        // 括弧の外の空白だけがトークン境界
+        if (depth === 0 && /\s/.test(c)) {
+            if (current !== "") {
+                tokens.push(current)
+                current = ""
+            }
+        } else {
+            current += c
+        }
+    }
+    if (current !== "") {
+        tokens.push(current)
+    }
+    return tokens
+}
+
+/** Class rules of a document plus the `table` rule's displayed-number separators. / 文書のクラス規則と `table` 規則の表示数値区切り。 */
+type StyleRules = { readonly classes: ReadonlyMap<string, ReadonlyMap<string, string>>; readonly separators: NumberSeparators }
+
+/** Class selector: `.name` or `tag.name` (Excel's `td.xl65`). / クラスセレクタ: `.name` か `tag.name` (Excel の `td.xl65`)。 */
+const CLASS_SELECTOR = /^(?:[a-z][a-z0-9]*)?\.([A-Za-z_-][\w-]*)$/i
+
+/**
+ * Reads every `<style>` element's RAW text: HTML comment markers and CSS comments stripped, each
+ * `selector { body }` tokenised through tokenizeInlineStyle, class selectors collected (a class
+ * declared twice merges, later wins), at-rules skipped, and the `table` rule's
+ * `mso-displayed-decimal-separator` / `mso-displayed-thousand-separator` decoded — used only when
+ * both are declared, the decimal is non-empty and the two differ (else the stated default).
+ * 全 `<style>` の生文字列を読む: HTML コメント印と CSS コメントを除き、各 `selector { body }` を
+ * tokenizeInlineStyle で分解、クラスセレクタを集め (重複宣言は後勝ちで併合)、at 規則は飛ばし、
+ * `table` 規則の区切り宣言を復号 — 両方宣言され小数区切りが非空で両者が異なるときだけ採用 (他は既定)。
+ */
+const readStyleRules = (doc: Document): StyleRules => {
+    const classes = new Map<string, Map<string, string>>()
+    let decimal: string | null = null
+    let group: string | null = null
+    for (const styleElement of doc.querySelectorAll("style")) {
+        // <style> は raw text 要素 — innerHTML はその文字列そのもの (エスケープなし)
+        const css = styleElement.innerHTML
+            .replaceAll("<!--", "")
+            .replaceAll("-->", "")
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+        let i = 0
+        while (i < css.length) {
+            const open = css.indexOf("{", i)
+            if (open === -1) {
+                break
+            }
+            const close = css.indexOf("}", open + 1)
+            if (close === -1) {
+                break
+            }
+            const selectors = css.slice(i, open)
+            const body = css.slice(open + 1, close)
+            i = close + 1
+            // at 規則 (@page 等) はセルに関係しない
+            if (selectors.trim().startsWith("@")) {
+                continue
+            }
+            const declarations = tokenizeInlineStyle(body)
+            for (const selector of selectors.split(",")) {
+                const trimmed = selector.trim()
+                const classMatch = CLASS_SELECTOR.exec(trimmed)
+                if (classMatch !== null) {
+                    const existing = classes.get(classMatch[1])
+                    if (existing === undefined) {
+                        classes.set(classMatch[1], new Map(declarations))
+                    } else {
+                        for (const [name, value] of declarations) {
+                            existing.set(name, value)
+                        }
+                    }
+                } else if (trimmed.toLowerCase() === "table") {
+                    // 区切り宣言は Excel の CSS 文字列エスケープを解く
+                    const decimalRaw = declarations.get("mso-displayed-decimal-separator")
+                    const groupRaw = declarations.get("mso-displayed-thousand-separator")
+                    if (decimalRaw !== undefined) {
+                        decimal = decodeMsoNumberFormat(stripCssQuotes(decimalRaw))
+                    }
+                    if (groupRaw !== undefined) {
+                        group = decodeMsoNumberFormat(stripCssQuotes(groupRaw))
+                    }
+                }
+            }
+        }
+    }
+    // 退化した宣言 (小数区切りが空 / 両者同一) は numberDisplayToCanonical が拒む — 既定へ
+    const separators = decimal !== null && group !== null && decimal !== "" && group !== decimal ? { group, decimal } : DEFAULT_HTML_SEPARATORS
+    return { classes, separators }
+}
+
+// ---------------------------------------------------------------------------------------------
+// mso-number-format encoding and the serial calendar
+// mso-number-format のエンコードとシリアル暦
+// ---------------------------------------------------------------------------------------------
+
+/** Pattern characters Excel leaves unescaped inside the CSS string besides alphanumerics. / 英数字以外で Excel が CSS 文字列内にそのまま書くパターン文字。 */
+const MSO_BARE_CHARS = "%_-*? "
+
+/**
+ * Applies Excel's CSS-string escaping to a number-format pattern (research map §6 rule 2): `"` →
+ * `\0022` (four hex digits, no terminator), `\` → `\\`, letters / digits / `% _ - * ?` / space /
+ * non-ASCII kept, every other character backslash-escaped. The exact inverse of
+ * `decodeMsoNumberFormat` (`decode(encode(p)) === p` for every pattern).
+ * 数値書式パターンへ Excel の CSS 文字列エスケープを施す: `"` → `\0022`、`\` → `\\`、英数字 /
+ * `% _ - * ?` / 空白 / 非 ASCII はそのまま、他は逆斜線エスケープ。`decodeMsoNumberFormat` の厳密な逆。
+ */
+export const encodeMsoNumberFormat = (pattern: string): string => {
+    let out = ""
+    for (const c of pattern) {
+        if (c === '"') {
+            out += "\\0022"
+        } else if (c === "\\") {
+            out += "\\\\"
+        } else if (/[A-Za-z0-9]/.test(c) || MSO_BARE_CHARS.includes(c) || c.charCodeAt(0) >= 0x80) {
+            out += c
+        } else {
+            out += `\\${c}`
+        }
+    }
+    return out
+}
+
+/** Days since 1970-01-01 of a proleptic-Gregorian civil date (Hinnant's algorithm). / 先発グレゴリオ暦の日付 → 1970-01-01 起点の日数 (Hinnant の算法)。 */
+const daysFromCivil = (year: number, month: number, day: number): number => {
+    const y = month <= 2 ? year - 1 : year
+    const era = Math.floor(y / 400)
+    const yoe = y - era * 400
+    const mp = month > 2 ? month - 3 : month + 9
+    const doy = Math.floor((153 * mp + 2) / 5) + day - 1
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy
+    return era * 146097 + doe - 719468
+}
+
+/** Civil date of a day count since 1970-01-01 (inverse of daysFromCivil). / 1970-01-01 起点の日数 → 日付 (daysFromCivil の逆)。 */
+const civilFromDays = (days: number): { readonly year: number; readonly month: number; readonly day: number } => {
+    const z = days + 719468
+    const era = Math.floor(z / 146097)
+    const doe = z - era * 146097
+    const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365)
+    const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100))
+    const mp = Math.floor((5 * doy + 2) / 153)
+    const day = doy - Math.floor((153 * mp + 2) / 5) + 1
+    const month = mp < 10 ? mp + 3 : mp - 9
+    return { year: yoe + era * 400 + (month <= 2 ? 1 : 0), month, day }
+}
+
+/** Zero-pads an integer to `width` digits. / 整数を `width` 桁にゼロ埋め。 */
+const pad = (value: number, width: number): string => String(value).padStart(width, "0")
+
+/**
+ * A FINITE Sheets / Excel date serial (days since 1899-12-30, fraction = time of day) → the
+ * package's ISO text: `YYYY-MM-DD`, plus ` HH:mm:ss` when the fraction is non-zero (seconds
+ * rounded, a round-up past midnight rolls the day). Null outside the grammar's serial domain
+ * [SERIAL_GRAMMAR_MIN, SERIAL_GRAMMAR_MAX] — converting there would synthesise structurally
+ * broken pseudo-ISO text that isoDateToSerial cannot round-trip, so the callers keep the
+ * display text instead. Pure integer calendar math; both callers reject non-finite serials
+ * before calling.
+ * 有限の Sheets / Excel 日付シリアル (1899-12-30 起点、小数部 = 時刻) → パッケージの ISO 文字列:
+ * `YYYY-MM-DD`、小数部があれば ` HH:mm:ss` (秒は四捨五入、繰り上がりは翌日へ)。文法のシリアル域
+ * [SERIAL_GRAMMAR_MIN, SERIAL_GRAMMAR_MAX] の外は null — 域外を変換すると isoDateToSerial が
+ * 往復できない壊れた疑似 ISO 文字列を合成するため、呼び手は可視文字列を保つ。純整数暦。非有限は
+ * 両呼び手が事前に弾く。
+ */
+const serialToIsoDate = (serial: number): string | null => {
+    // 域外の暦計算は "2.73…e+297-03-01" / "00-1-12-31" の様な文法外文字列を作るため変換しない
+    if (serial < SERIAL_GRAMMAR_MIN || serial > SERIAL_GRAMMAR_MAX) {
+        return null
+    }
+    let days = Math.floor(serial)
+    let seconds = Math.round((serial - days) * SECONDS_PER_DAY)
+    // 四捨五入で 1 日分に達したら翌日の 0 時
+    if (seconds >= SECONDS_PER_DAY) {
+        days += 1
+        seconds -= SECONDS_PER_DAY
+    }
+    const civil = civilFromDays(days + SERIAL_EPOCH_DAYS)
+    const date = `${pad(civil.year, 4)}-${pad(civil.month, 2)}-${pad(civil.day, 2)}`
+    if (seconds === 0) {
+        return date
+    }
+    const hours = Math.floor(seconds / 3600)
+    const minutes = Math.floor((seconds % 3600) / 60)
+    return `${date} ${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds % 60, 2)}`
+}
+
+/** The package date grammar: `YYYY-MM-DD` or `YYYY/MM/DD`, optional ` HH:mm[:ss]` / `THH:mm[:ss]`. / パッケージの日付文法。 */
+const ISO_DATE = /^(\d{4})([-/])(\d{2})\2(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/
+
+/**
+ * The package's ISO date text → a Sheets / Excel serial (days since 1899-12-30 + fraction of
+ * the day); null when the text is not a valid calendar date-time (a 31st of April, 24:00, mixed
+ * separators). Exact inverse of serialToIsoDate on the grammar.
+ * パッケージの ISO 日付文字列 → Sheets / Excel シリアル。暦として無効 (4 月 31 日、24 時、区切り混在)
+ * なら null。文法上 serialToIsoDate の厳密な逆。
+ */
+const isoDateToSerial = (text: string): number | null => {
+    const match = ISO_DATE.exec(text)
+    if (match === null) {
+        return null
+    }
+    const year = Number(match[1])
+    const month = Number(match[3])
+    const day = Number(match[4])
+    const hours = match[5] === undefined ? 0 : Number(match[5])
+    const minutes = match[6] === undefined ? 0 : Number(match[6])
+    const seconds = match[7] === undefined ? 0 : Number(match[7])
+    if (month < 1 || month > 12 || day < 1 || hours > 23 || minutes > 59 || seconds > 59) {
+        return null
+    }
+    // 暦の往復で日付の実在を検証 (4 月 31 日は 5 月 1 日へ写り不一致)
+    const days = daysFromCivil(year, month, day)
+    const back = civilFromDays(days)
+    if (back.year !== year || back.month !== month || back.day !== day) {
+        return null
+    }
+    return days - SERIAL_EPOCH_DAYS + (hours * 3600 + minutes * 60 + seconds) / SECONDS_PER_DAY
+}
+
+// ---------------------------------------------------------------------------------------------
+// Writer
+// writer
+// ---------------------------------------------------------------------------------------------
+
+/** Escapes text content (`& < >`). / テキスト内容のエスケープ (`& < >`)。 */
+const escapeText = (text: string): string => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+
+/** Escapes a double-quoted attribute value. / 二重引用の属性値のエスケープ。 */
+const escapeAttribute = (text: string): string => escapeText(text).replaceAll('"', "&quot;")
+
+/** Escapes a single-quoted attribute value (the clip JSON and the style attribute keep raw `"`). / 単一引用の属性値のエスケープ (クリップ JSON と style 属性は `"` を素のまま保つ)。 */
+const escapeSingleQuoted = (text: string): string => escapeText(text).replaceAll("'", "&#39;")
+
+/** One cell's inner HTML: escape, then newline / tab forms. / セル 1 つの内側 HTML: エスケープ後に改行 / タブ形。 */
+const serializeContent = (text: string): string => escapeText(text).replaceAll("\r\n", "\n").replaceAll("\r", "\n").replaceAll("\n", '<br style="mso-data-placement:same-cell">').replaceAll("\t", "&#9;")
+
+/** A JSON-valued Sheets attribute in Sheets' own `&quot;` form. / Sheets 自身の `&quot;` 形の JSON 属性。 */
+const sheetsJsonAttribute = (name: string, value: unknown): string => `${name}="${escapeAttribute(JSON.stringify(value))}"`
+
+/** The numeric value-format types (the ones whose text is a decimal). / 数値系の値書式型 (文字列が 10 進であるもの)。 */
+type NumericValueFormat =
+    | { type: "number"; decimals?: number; grouping?: boolean; locale?: string }
+    | { type: "percent"; decimals?: number; scale?: boolean; locale?: string }
+    | { type: "currency"; currency: string; decimals?: number; locale?: string }
+    | { type: "scientific"; decimals?: number; locale?: string }
+
+/** Numeric value-format guard. / 数値系値書式のガード。 */
+const isNumericValueFormat = (value: CellValueFormat): value is NumericValueFormat => value.type === "number" || value.type === "percent" || value.type === "currency" || value.type === "scientific"
+
+/** The finite double of a strict-decimal text, or null (non-decimal / overflowing). / 厳密 10 進文字列の有限 double、なければ null (非 10 進 / 桁溢れ)。 */
+const finiteNumberOf = (text: string): number | null => {
+    if (parseNumber(text) === null) {
+        return null
+    }
+    const n = Number(text)
+    return Number.isFinite(n) ? n : null
+}
+
+/** Sheets `NumberFormatType` for a date pattern: 5 DATE, 6 TIME, 7 DATE_TIME by the tokens present. / 日付パターンの Sheets 型コード (存在するトークンで 5 / 6 / 7)。 */
+const sheetsDateCode = (pattern: string): number => {
+    const hasDate = /yyyy|MM|dd/.test(pattern)
+    const hasTime = /HH|mm|ss/.test(pattern)
+    return hasDate && hasTime ? 7 : hasTime ? 6 : 5
+}
+
+/** The `data-sheets-numberformat` object of a value format, or null when Excel / Sheets cannot express it. / 値書式の `data-sheets-numberformat` オブジェクト、表現不能は null。 */
+const sheetsNumberFormat = (value: CellValueFormat): Record<string, unknown> | null => {
+    if (value.type === "text") {
+        return { "1": 1 }
+    }
+    const pattern = toExcelPattern(value)
+    if (pattern === null) {
+        return null
+    }
+    // "3":1 = 明示パターン (ユーザー指定形) — Sheets がパターンをそのまま尊重する
+    const code = value.type === "date" ? sheetsDateCode(value.pattern === undefined ? "yyyy/MM/dd" : value.pattern) : SHEETS_NUMBER_FORMAT_CODE[value.type]
+    return { "1": code, "2": pattern, "3": 1 }
+}
+
+/** Characters a font family may not carry into a style attribute (declaration / markup injection). / style 属性へ持ち込めないフォント族の文字 (宣言 / マークアップ注入)。 */
+const UNSAFE_FAMILY = /[;"'{}<>&\\]/
+
+/** Closed-vocabulary guard for align. / align の閉じた語彙ガード。 */
+const isCellAlign = (value: unknown): value is CellAlign => value === "left" || value === "center" || value === "right"
+
+/** Closed-vocabulary guard for verticalAlign. / verticalAlign の閉じた語彙ガード。 */
+const isVerticalAlign = (value: unknown): value is CellVerticalAlign => value === "top" || value === "middle" || value === "bottom"
+
+/**
+ * CSS declarations of a format in the shared vocabulary (order fixed): font-weight, font-style,
+ * text-decoration, color, background-color, text-align, vertical-align, font-family (skipped when
+ * it holds injection characters), font-size in pt (finite positive only), one `border-<side>` per
+ * declared side (`windowtext` for the default colour; a side with an unknown style or an
+ * unparseable colour is skipped whole), and `mso-number-format` when `toExcelPattern` can express
+ * the value format. Booleans count only when strictly `true`.
+ * 書式の CSS 宣言 (共通語彙、順序固定)。フォント族は注入文字を含めば省略、フォントサイズは有限正のみ、
+ * 罫線は宣言された辺だけ (既定色は `windowtext`、未知の線種 / 解釈不能な色の辺は丸ごと省略)、
+ * `mso-number-format` は `toExcelPattern` が表現できるときだけ。真偽値は厳密 true のみ。
+ */
+const formatCss = (format: CellFormat): string[] => {
+    const css: string[] = []
+    if (format.bold === true) {
+        css.push("font-weight:bold")
+    }
+    if (format.italic === true) {
+        css.push("font-style:italic")
+    }
+    const decorations = [...(format.underline === true ? ["underline"] : []), ...(format.strikethrough === true ? ["line-through"] : [])]
+    if (decorations.length > 0) {
+        css.push(`text-decoration:${decorations.join(" ")}`)
+    }
+    const color = typeof format.color === "string" ? normalizeColor(format.color) : null
+    if (color !== null) {
+        css.push(`color:${color}`)
+    }
+    const background = typeof format.background === "string" ? normalizeColor(format.background) : null
+    if (background !== null) {
+        css.push(`background-color:${background}`)
+    }
+    if (isCellAlign(format.align)) {
+        css.push(`text-align:${format.align}`)
+    }
+    if (isVerticalAlign(format.verticalAlign)) {
+        css.push(`vertical-align:${format.verticalAlign}`)
+    }
+    if (typeof format.fontFamily === "string" && format.fontFamily.trim() !== "" && !UNSAFE_FAMILY.test(format.fontFamily)) {
+        css.push(`font-family:${format.fontFamily.trim()}`)
+    }
+    if (typeof format.fontSize === "number" && Number.isFinite(format.fontSize) && format.fontSize > 0) {
+        css.push(`font-size:${format.fontSize}pt`)
+    }
+    if (format.borders !== undefined) {
+        for (const side of BORDER_SIDES) {
+            const border = format.borders[side]
+            // 語彙外の線種は辺ごと省略 (prototype キーも Object.hasOwn で弾く)
+            if (border === undefined || !Object.hasOwn(BORDER_CSS, border.style)) {
+                continue
+            }
+            const borderColor = border.color === undefined ? "windowtext" : normalizeColor(border.color)
+            if (borderColor !== null) {
+                css.push(`border-${side}:${BORDER_CSS[border.style]} ${borderColor}`)
+            }
+        }
+    }
+    if (format.value !== undefined) {
+        const pattern = toExcelPattern(format.value)
+        if (pattern !== null) {
+            css.push(`mso-number-format:"${encodeMsoNumberFormat(pattern)}"`)
+        }
+    }
+    return css
+}
+
+/**
+ * The cell-independent, format-derived parts of a `<td>`, derived ONCE per dictionary index by
+ * `serializeHtmlTable`: the escaped `style` attribute value (white-space mode + `formatCss`
+ * joined) and the complete `data-sheets-numberformat` attribute (null when the format has no
+ * expressible value format), plus the value format the per-cell classification still needs.
+ * These are pure functions of the format object — recomputing them per cell costs O(cells ×
+ * format work) where the `fmt` dictionary makes O(distinct formats) available (~half of the
+ * 100k-cell HTML serialize wall time).
+ * `<td>` の書式由来でセル非依存の部分 (`serializeHtmlTable` が辞書 index 毎に 1 回だけ導出):
+ * エスケープ済み `style` 属性値 (white-space モード + `formatCss` の結合) と `data-sheets-numberformat`
+ * 属性の完成形 (表現できる値書式が無ければ null)、およびセル毎の分類が引き続き要る値書式。
+ * いずれも書式オブジェクトの純関数 — セル毎の再計算は O(セル数 × 書式処理) で、`fmt` 辞書は
+ * O(異なり書式数) を可能にしている (100k セル HTML 直列化の壁時計の約半分)。
+ */
+type SerializedFormat = { readonly value: CellValueFormat | undefined; readonly style: string; readonly numberFormatAttribute: string | null }
+
+/** The parts of a format-less cell (exactly `<td style='white-space:pre'>`). / 書式なしセルの部分 (正確に `<td style='white-space:pre'>`)。 */
+const PLAIN_SERIALIZED_FORMAT: SerializedFormat = { value: undefined, style: "white-space:pre", numberFormatAttribute: null }
+
+/**
+ * Derives the `SerializedFormat` of one dictionary entry (see the type's contract).
+ * 辞書エントリ 1 つの `SerializedFormat` を導出する (契約は型に記載)。
+ */
+const serializeFormat = (format: CellFormat): SerializedFormat => {
+    const value = format.value
+    const whiteSpace = format.wrap === true ? "white-space:pre-wrap;word-wrap:break-word" : "white-space:pre"
+    const style = escapeSingleQuoted([whiteSpace, ...formatCss(format)].join(";"))
+    let numberFormatAttribute: string | null = null
+    if (value !== undefined) {
+        const numberFormat = sheetsNumberFormat(value)
+        if (numberFormat !== null) {
+            numberFormatAttribute = sheetsJsonAttribute("data-sheets-numberformat", numberFormat)
+        }
+    }
+    return { value, style, numberFormatAttribute }
+}
+
+/**
+ * One `<td>`: the style attribute (single-quoted like Excel so `mso-number-format` keeps its
+ * double quotes), then the Sheets typed attributes, then the Excel typed attributes, then the
+ * display text (wrapped in `<a href>` for a link). Attributes appear only for the aspects the cell
+ * has, so a plain cell is exactly `<td style='white-space:pre'>text</td>`. `format` carries the
+ * memoised format-derived strings; the per-cell work here depends on the cell's own text / aspects.
+ * `<td>` 1 つ: style 属性 (Excel 同様の単一引用で `mso-number-format` の二重引用を保つ)、Sheets の
+ * 型付き属性、Excel の型付き属性、表示文字列 (リンクは `<a href>` で包む)。属性はセルが持つ側面の
+ * 分だけ出るので、素のセルは正確に `<td style='white-space:pre'>text</td>`。`format` は memo 済みの
+ * 書式由来文字列 — ここでのセル毎の仕事はセル自身の文字列 / 側面にだけ依存する。
+ */
+const serializeCell = (cell: ClipCell, format: SerializedFormat, row: number, col: number): string => {
+    const value = format.value
+    const display = value === undefined ? cell.t : formatCellValue(cell.t, value)
+    // 型付き値の分類: "=" リテラル / text 書式は文字列、数値書式 + 10 進は数値、date 書式 + ISO はシリアル
+    const stringLiteral = cell.t !== "" && ((value !== undefined && value.type === "text") || cell.t.startsWith("="))
+    const numeric = !stringLiteral && value !== undefined && isNumericValueFormat(value) ? finiteNumberOf(cell.t) : null
+    const serial = !stringLiteral && numeric === null && value !== undefined && value.type === "date" ? isoDateToSerial(cell.t) : null
+    const attributes: string[] = []
+    if (stringLiteral) {
+        attributes.push(sheetsJsonAttribute("data-sheets-value", { "1": 2, "2": cell.t }))
+    } else if (numeric !== null) {
+        attributes.push(sheetsJsonAttribute("data-sheets-value", { "1": 3, "3": numeric }))
+    } else if (serial !== null) {
+        attributes.push(sheetsJsonAttribute("data-sheets-value", { "1": 3, "3": serial }))
+    }
+    if (cell.f !== undefined) {
+        attributes.push(`data-sheets-formula="${escapeAttribute(cell.f)}"`)
+    }
+    if (format.numberFormatAttribute !== null) {
+        attributes.push(format.numberFormatAttribute)
+    }
+    if (cell.link !== undefined) {
+        attributes.push(`data-sheets-hyperlink="${escapeAttribute(cell.link)}"`)
+    }
+    if (cell.note !== undefined) {
+        attributes.push(`data-sheets-note="${escapeAttribute(cell.note)}"`)
+    }
+    if (stringLiteral) {
+        attributes.push("x:str")
+    } else if (numeric !== null) {
+        attributes.push(`x:num="${escapeAttribute(cell.t)}"`)
+    } else if (serial !== null) {
+        attributes.push(`x:num="${serial}"`)
+    }
+    if (cell.f !== undefined) {
+        // クリップを A1 に置いた A1 形。クリップ外へ落ちる参照 (#REF!) は Excel へ渡さない
+        const a1 = fromR1C1(cell.f, { row, col })
+        if (!a1.includes("#REF!")) {
+            attributes.push(`x:fmla="${escapeAttribute(a1)}"`)
+        }
+    }
+    const content = serializeContent(display)
+    const body = cell.link === undefined ? content : `<a href="${escapeAttribute(cell.link)}">${content}</a>`
+    return `<td style='${format.style}'${attributes.map((attribute) => ` ${attribute}`).join("")}>${body}</td>`
+}
+
+/**
+ * Serializes a clip payload to the interop HTML table (see the fileoverview writer contract).
+ * `clipJson` is the payload's `serializeClipPayload` string (the caller already holds it for the
+ * custom MIME flavour) and becomes the FIRST attribute of `<table>`. A payload whose `cells`
+ * matrix is not `rows × cols` is a RangeError (consumer input on an API surface).
+ * クリップ payload を相互運用 HTML 表へ直列化 (fileoverview の writer 契約)。`clipJson` は payload の
+ * `serializeClipPayload` 文字列 (呼び手はカスタム MIME 用に既に持つ) で `<table>` の先頭属性になる。
+ * `cells` が `rows × cols` でない payload は RangeError (API 面の消費者入力)。
+ */
+export const serializeHtmlTable = (payload: ClipPayload, clipJson: string): string => {
+    if (payload.cells.length !== payload.rows || payload.cells.some((row) => row.length !== payload.cols)) {
+        throw new RangeError(`serializeHtmlTable: cells must be exactly rows × cols (${payload.rows} × ${payload.cols})`)
+    }
+    const colgroup = payload.colWidths === undefined ? "" : `<colgroup>${payload.colWidths.map((width) => `<col width="${width}">`).join("")}</colgroup>`
+    // 書式由来の文字列 (style / data-sheets-numberformat) は辞書 index 毎に 1 回だけ導出する —
+    // セル毎の再計算は O(セル数 × 書式処理) で、100k copy の HTML 直列化の壁時計の約半分を占めていた
+    const formats = payload.formats.map(serializeFormat)
+    let rows = ""
+    for (let r = 0; r < payload.rows; r += 1) {
+        const height = payload.rowHeights === undefined ? "" : ` height="${payload.rowHeights[r]}" style="height:${payload.rowHeights[r]}px;"`
+        let cells = ""
+        for (let c = 0; c < payload.cols; c += 1) {
+            const cell = payload.cells[r][c]
+            // 辞書範囲外の fmt は旧来どおり書式なしセルと同じ直列化 (契約上は serializeClipPayload が先に拒む)
+            const memo = cell.fmt === undefined ? undefined : formats[cell.fmt]
+            cells += serializeCell(cell, memo === undefined ? PLAIN_SERIALIZED_FORMAT : memo, r, c)
+        }
+        rows += `<tr${height}>${cells}</tr>`
+    }
+    return `<${SHEETS_ORIGIN_TAG}><style type="text/css">br{mso-data-placement:same-cell;}</style><table ${CLIP_ATTRIBUTE}='${escapeSingleQuoted(clipJson)}' data-sheets-root="1" cellspacing="0" cellpadding="0" border="1" style="table-layout:fixed;border-collapse:collapse">${colgroup}<tbody>${rows}</tbody></table></${SHEETS_ORIGIN_TAG}>`
+}
+
+// ---------------------------------------------------------------------------------------------
+// Reader — CSS vocabulary → CellFormat
+// reader — CSS 語彙 → CellFormat
+// ---------------------------------------------------------------------------------------------
+
+/** Mutable declaration map (class rules merged into inline). / 可変の宣言 map (クラス規則 + インライン)。 */
+type Declarations = Map<string, string>
+
+/** Decorations contributed by run TAGS (`u`, `s`, …), additive to the declared tokens. / run タグ (`u`, `s` …) が寄与する装飾 (宣言トークンへ加算)。 */
+type RunFlags = { underline: boolean; strikethrough: boolean }
+
+/** What the reader needs per document. / reader が文書毎に要するもの。 */
+type ReadContext = { readonly kind: HtmlTableKind; readonly rules: StyleRules; readonly options: NumberFormatDecodeOptions; readonly separators: NumberSeparators }
+
+/** Merges `source` into `target` (later wins). / `source` を `target` へ併合 (後勝ち)。 */
+const mergeDeclarations = (target: Declarations, source: ReadonlyMap<string, string>): void => {
+    for (const [name, value] of source) {
+        target.set(name, value)
+    }
+}
+
+/**
+ * The declarations of an element in cascade order: the `bgcolor` attribute (lowest — entered as
+ * the `background` shorthand so any CSS declaration wins over it), class rules in class-list
+ * order, then the inline `style`.
+ * 要素の宣言 (カスケード順): `bgcolor` 属性 (最下位 — `background` 短縮形として入れ、CSS 宣言が
+ * 属性に勝つ)、クラス一覧順のクラス規則、インライン `style`。
+ */
+const declarationsOf = (element: Element, rules: StyleRules): Declarations => {
+    const merged: Declarations = new Map()
+    const bgcolor = element.getAttribute("bgcolor")
+    if (bgcolor !== null && bgcolor.trim() !== "") {
+        merged.set("background", bgcolor)
+    }
+    for (const className of element.classList) {
+        const classDeclarations = rules.classes.get(className)
+        if (classDeclarations !== undefined) {
+            mergeDeclarations(merged, classDeclarations)
+        }
+    }
+    const style = element.getAttribute("style")
+    if (style !== null) {
+        mergeDeclarations(merged, tokenizeInlineStyle(style))
+    }
+    return merged
+}
+
+/** A border width: its pt value and the unit it was declared in (keywords count as px). / 罫線幅: pt 値と宣言単位 (キーワードは px 扱い)。 */
+type BorderWidth = { readonly pt: number; readonly unit: "pt" | "px" }
+
+/** Border width from a CSS token (`0.5pt`, `2px`; the keywords as 1 / 2 / 3 px so they map to their own names), or null. / CSS トークンからの罫線幅 (キーワードは同名へ写るよう 1 / 2 / 3 px)、なければ null。 */
+const borderWidthOf = (token: string): BorderWidth | null => {
+    const lower = token.toLowerCase()
+    if (lower === "thin") {
+        return { pt: 0.75, unit: "px" }
+    }
+    if (lower === "medium") {
+        return { pt: 1.5, unit: "px" }
+    }
+    if (lower === "thick") {
+        return { pt: 3, unit: "px" }
+    }
+    const match = /^(\d*\.?\d+)(pt|px)$/.exec(lower)
+    if (match === null) {
+        return null
+    }
+    const n = Number(match[1])
+    return match[2] === "pt" ? { pt: n, unit: "pt" } : { pt: n * 0.75, unit: "px" }
+}
+
+/**
+ * Solid-line style from a width: px widths follow Sheets (1 / 2 / ≥ 3 px), pt widths follow Excel
+ * (`.5pt` thin, `1.0pt` medium, `1.5pt` thick) — thresholds < 0.75 / < 1.25 pt.
+ * 幅からの実線種: px は Sheets (1 / 2 / 3 px 以上)、pt は Excel (.5 / 1.0 / 1.5pt) — 閾値 0.75 / 1.25pt。
+ */
+const solidStyleOf = (width: BorderWidth): CellBorderStyle => {
+    if (width.unit === "px") {
+        const px = width.pt / 0.75
+        return px <= 1 ? "thin" : px < 3 ? "medium" : "thick"
+    }
+    return width.pt < 0.75 ? "thin" : width.pt < 1.25 ? "medium" : "thick"
+}
+
+/** Style keyword → package border style (solid-like keywords defer to the width). / 線種キーワード → パッケージの罫線種 (実線系は幅に委ねる)。 */
+const BORDER_STYLE_OF: ReadonlyMap<string, CellBorderStyle> = new Map([
+    ["dashed", "dashed"],
+    ["dotted", "dotted"],
+    ["double", "double"],
+    ["hairline", "hair"],
+])
+
+/** CSS `medium` — the width when a border value declares none (maps to the medium style). / CSS の `medium` — 幅の宣言が無いときの幅 (medium 線種へ写る)。 */
+const CSS_MEDIUM_WIDTH: BorderWidth = { pt: 1.5, unit: "px" }
+
+/**
+ * One border side from a CSS border value: `null` when the side is absent (`none` / `hidden`, no
+ * style token, a transparent or unparseable colour); otherwise the style (keyword, else by width —
+ * a missing width is CSS `medium`) and the colour (omitted for `windowtext` / `currentcolor`).
+ * CSS の border 値から 1 辺: 辺なし (`none` / `hidden`、線種トークンなし、透明 / 解釈不能な色) は
+ * null、他は線種 (キーワード、なければ幅から — 幅なしは CSS の `medium`) と色 (`windowtext` /
+ * `currentcolor` は省略)。
+ */
+const parseBorderValue = (value: string): CellBorder | null => {
+    let width: BorderWidth | null = null
+    let keyword: string | null = null
+    const colorTokens: string[] = []
+    for (const token of splitCssTokens(value)) {
+        const lower = token.toLowerCase()
+        const asWidth = borderWidthOf(token)
+        if (BORDER_STYLE_KEYWORDS.has(lower)) {
+            keyword = lower
+        } else if (asWidth !== null) {
+            width = asWidth
+        } else {
+            colorTokens.push(token)
+        }
+    }
+    // 線種トークンが無い / none / hidden は辺なし (CSS の既定 style は none)
+    if (keyword === null || keyword === "none" || keyword === "hidden") {
+        return null
+    }
+    const mapped = BORDER_STYLE_OF.get(keyword)
+    const style = mapped === undefined ? solidStyleOf(width === null ? CSS_MEDIUM_WIDTH : width) : mapped
+    const colorText = colorTokens.join(" ")
+    if (colorText === "" || DEFAULT_COLOR_WORDS.has(colorText.toLowerCase())) {
+        return { style }
+    }
+    const color = normalizeColor(colorText)
+    // 解釈不能な色は辺ごとスキップ、透明 (alpha 00) は罫線なし
+    if (color === null || color.length === 9) {
+        return null
+    }
+    return { style, color }
+}
+
+/** Sheets' own grid-line declaration (the `td` rule a sanitising engine inlines) — not a user border. / Sheets 自身の罫線既定 (サニタイズ engine がインライン化する `td` 規則) — ユーザーの罫線ではない。 */
+const isSheetsGridLine = (border: CellBorder): boolean => border.style === "thin" && border.color === "#cccccc"
+
+/** Colour of a `background` shorthand: the whole value, else the first token normalizeColor accepts. / `background` 短縮形の色: 値全体、なければ normalizeColor が受ける最初のトークン。 */
+const colorFromShorthand = (value: string): string | null => {
+    const whole = normalizeColor(value)
+    if (whole !== null) {
+        return whole
+    }
+    for (const token of splitCssTokens(value)) {
+        const color = normalizeColor(token)
+        if (color !== null) {
+            return color
+        }
+    }
+    return null
+}
+
+/** The first family of a `font-family` list, unquoted; null for a generic keyword or nothing. / `font-family` 一覧の先頭族 (引用符なし)、総称キーワード / 空は null。 */
+const firstFontFamily = (value: string): string | null => {
+    const first = stripCssQuotes(splitCssTokens(value.split(",")[0]).join(" ").trim()).trim()
+    return first === "" || GENERIC_FAMILIES.has(first.toLowerCase()) ? null : first
+}
+
+/** `font-size` in pt from `NNpt` / `NNpx` (× 0.75); null for keywords, percentages, em, non-positive. / `NNpt` / `NNpx` (× 0.75) からの pt サイズ、キーワード / % / em / 非正は null。 */
+const fontSizePt = (value: string): number | null => {
+    const match = /^(\d*\.?\d+)(pt|px)$/i.exec(value.trim())
+    if (match === null) {
+        return null
+    }
+    const n = Number(match[1])
+    const pt = match[2].toLowerCase() === "pt" ? n : n * 0.75
+    return Number.isFinite(pt) && pt > 0 ? pt : null
+}
+
+/** Decoration tokens of `text-decoration` and `text-decoration-line` (union, `none` contributes nothing). / `text-decoration` と `text-decoration-line` の装飾トークン (和集合、`none` は寄与しない)。 */
+const decorationTokens = (declarations: Declarations): ReadonlySet<string> => {
+    const tokens = new Set<string>()
+    for (const name of ["text-decoration", "text-decoration-line"]) {
+        const value = declarations.get(name)
+        if (value !== undefined) {
+            for (const token of value.toLowerCase().split(/\s+/)) {
+                tokens.add(token)
+            }
+        }
+    }
+    return tokens
+}
+
+/** The wrap / preserve mode of a cell from its `white-space`. / セルの `white-space` からの折返し / 保存モード。 */
+type WhiteSpaceMode = "collapse" | "pre" | "pre-line"
+
+/** `white-space` → text mode (`pre` / `pre-wrap` verbatim, `pre-line` newline-preserving, else collapse). / `white-space` → 文字列モード。 */
+const whiteSpaceModeOf = (declarations: Declarations): WhiteSpaceMode => {
+    const value = declarations.get("white-space")
+    const lower = value === undefined ? "" : value.toLowerCase()
+    return lower === "pre" || lower === "pre-wrap" ? "pre" : lower === "pre-line" ? "pre-line" : "collapse"
+}
+
+/** `white-space` values that mean "wrap". / 「折返し」を意味する `white-space` 値。 */
+const WRAP_VALUES: ReadonlySet<string> = new Set(["normal", "pre-wrap", "pre-line"])
+
+/**
+ * Builds the CellFormat a cell's merged declarations describe (the vocabulary mapping of the
+ * fileoverview). Values outside the closed vocabularies are skipped, never substituted; the
+ * value format is attached by the kind-specific caller.
+ * セルの併合済み宣言が表す CellFormat を組む (fileoverview の語彙写像)。閉じた語彙の外は代替せず
+ * スキップ。値書式は kind 毎の呼び手が付ける。
+ */
+const formatFromDeclarations = (declarations: Declarations, flags: RunFlags, kind: HtmlTableKind): CellFormat => {
+    const format: CellFormat = {}
+    const weight = declarations.get("font-weight")
+    if (weight !== undefined) {
+        const lower = weight.toLowerCase()
+        if (lower === "bold" || lower === "bolder" || Number(lower) >= 600) {
+            format.bold = true
+        }
+    }
+    const fontStyle = declarations.get("font-style")
+    if (fontStyle !== undefined && (fontStyle.toLowerCase() === "italic" || fontStyle.toLowerCase().startsWith("oblique"))) {
+        format.italic = true
+    }
+    const decorations = decorationTokens(declarations)
+    if (flags.underline || decorations.has("underline")) {
+        format.underline = true
+    }
+    if (flags.strikethrough || decorations.has("line-through")) {
+        format.strikethrough = true
+    }
+    const colorValue = declarations.get("color")
+    const color = colorValue === undefined ? null : normalizeColor(colorValue)
+    if (color !== null && color.length !== 9) {
+        format.color = color
+    }
+    // 長形 background-color が短縮形 background (と bgcolor 属性) に優先する
+    const backgroundValue = declarations.has("background-color") ? declarations.get("background-color") : declarations.get("background")
+    const background = backgroundValue === undefined ? null : colorFromShorthand(backgroundValue)
+    if (background !== null && background.length !== 9) {
+        format.background = background
+    }
+    const align = declarations.get("text-align")
+    const alignLower = align === undefined ? "" : align.toLowerCase()
+    if (isCellAlign(alignLower)) {
+        format.align = alignLower
+    }
+    const verticalAlign = declarations.get("vertical-align")
+    const verticalLower = verticalAlign === undefined ? "" : verticalAlign.toLowerCase()
+    if (isVerticalAlign(verticalLower)) {
+        format.verticalAlign = verticalLower
+    }
+    const family = declarations.get("font-family")
+    const firstFamily = family === undefined ? null : firstFontFamily(family)
+    if (firstFamily !== null) {
+        format.fontFamily = firstFamily
+    }
+    const size = declarations.get("font-size")
+    const pt = size === undefined ? null : fontSizePt(size)
+    if (pt !== null) {
+        format.fontSize = pt
+    }
+    const whiteSpace = declarations.get("white-space")
+    if (whiteSpace !== undefined && WRAP_VALUES.has(whiteSpace.toLowerCase())) {
+        format.wrap = true
+    }
+    const borders: CellBorders = {}
+    const shorthand = declarations.get("border")
+    const all = shorthand === undefined ? null : parseBorderValue(shorthand)
+    for (const side of BORDER_SIDES) {
+        const sideValue = declarations.get(`border-${side}`)
+        // 辺の宣言が短縮形に優先する
+        const border = sideValue === undefined ? all : parseBorderValue(sideValue)
+        if (border !== null && !(kind === "sheets" && isSheetsGridLine(border))) {
+            borders[side] = border
+        }
+    }
+    if (Object.keys(borders).length > 0) {
+        format.borders = borders
+    }
+    return format
+}
+
+// ---------------------------------------------------------------------------------------------
+// Reader — cell text and runs
+// reader — セル文字列と run
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * A run element and the `[before, end)` window of the walked text its subtree produced — offsets,
+ * never a copy, so capturing a run is O(1) whatever the nesting depth or text length.
+ * run 要素とその部分木が生んだ走査文字列の `[before, end)` 窓 — 複製でなくオフセット。捕捉は
+ * 入れ子深さ / 文字数に依らず run 1 つ O(1)。
+ */
+type RunCandidate = { readonly element: Element; readonly before: number; readonly end: number }
+
+/** The walk state of one cell. / セル 1 つの走査状態。 */
+type WalkState = { text: string; readonly runs: RunCandidate[]; href: string | null; readonly mode: WhiteSpaceMode }
+
+/** Ends the current line in collapse mode (once). / collapse モードで現在行を閉じる (1 回だけ)。 */
+const lineBoundary = (state: WalkState): void => {
+    if (state.text !== "" && !state.text.endsWith("\n")) {
+        state.text += "\n"
+    }
+}
+
+/** True when an element is an `mso-spacerun:yes` span (accounting padding — dropped whole). / 要素が `mso-spacerun:yes` の span (会計形式の詰め物 — 丸ごと落とす) なら true。 */
+const isSpaceRun = (element: Element): boolean => {
+    const style = element.getAttribute("style")
+    return style !== null && tokenizeInlineStyle(style).get("mso-spacerun") === "yes"
+}
+
+/** One traversal frame of `walkCell`: `enter` visits a node, `exit` closes an element (run capture + trailing line boundary). / `walkCell` の走査フレーム 1 つ: `enter` はノード訪問、`exit` は要素の閉じ (run 捕捉 + 後置きの行境界)。 */
+type WalkFrame = { readonly kind: "enter"; readonly node: Node } | { readonly kind: "exit"; readonly element: Element; readonly before: number; readonly block: boolean }
+
+/**
+ * Walks a cell subtree appending text to the state: text nodes (newlines / tabs → spaces in
+ * collapse mode, CR forms → LF otherwise), `<br>` → newline, skipped tags and space-run spans
+ * → nothing, block elements and nested rows → line boundaries (collapse mode), nested cells → a
+ * separating space, the first `<a href>` recorded, run elements recorded with their text WINDOW
+ * (start / end offsets — never a text copy, so a run costs O(1)).
+ * Iterative (explicit enter / exit stack over `lastChild` / `previousSibling`, same visit order
+ * as the recursive form): the call-stack depth is O(1) whatever the markup nesting — the total
+ * fail-soft contract must survive pathologically deep cells.
+ * セル部分木を走査して状態へ文字列を追記: テキストノード (collapse では改行 / タブ → 空白、他は CR 形
+ * → LF)、`<br>` → 改行、除外タグ / spacerun → 無、ブロック要素 / 入れ子行 → 行境界 (collapse)、入れ子
+ * セル → 区切り空白、最初の `<a href>` を記録、run 要素はその文字列**窓** (開始 / 終了オフセット —
+ * 文字列複製なし、run 1 つ O(1)) と共に記録。反復走査 (enter / exit の
+ * 明示スタック、`lastChild` / `previousSibling` — 訪問順は再帰形と同一): 呼び出しスタックの深さは
+ * マークアップの入れ子深さに依存しない O(1) — 病的に深いセルでも全域 fail-soft 契約を保つ。
+ */
+const walkCell = (root: Node, state: WalkState): void => {
+    const stack: WalkFrame[] = [{ kind: "enter", node: root }]
+    for (let frame = stack.pop(); frame !== undefined; frame = stack.pop()) {
+        // exit = 再帰の帰り道に相当: 子孫の生んだ文字列で run を捕捉し、ブロックの後置き行境界を閉じる
+        if (frame.kind === "exit") {
+            if (RUN_TAGS.has(frame.element.localName)) {
+                // run はオフセット窓だけ記録する — 深い入れ子 × 長文の敵対セルで run 毎の文字列
+                // 実体化が O(深さ × 文字数) の同期費用にならないため (readCell 側の判定も O(1))
+                state.runs.push({ element: frame.element, before: frame.before, end: state.text.length })
+            }
+            if (frame.block) {
+                lineBoundary(state)
+            }
+            continue
+        }
+        const node = frame.node
+        if (node.nodeType === TEXT_NODE) {
+            const data = (node as Text).data
+            state.text += state.mode === "collapse" ? data.replace(/[\r\n\t\f]/g, " ") : data.replace(/\r\n?/g, "\n")
+            continue
+        }
+        if (node.nodeType !== ELEMENT_NODE) {
+            continue
+        }
+        const element = node as Element
+        const tag = element.localName
+        if (SKIP_TAGS.has(tag) || isSpaceRun(element)) {
+            continue
+        }
+        if (tag === "br") {
+            state.text += "\n"
+            continue
+        }
+        const block = state.mode === "collapse" && BLOCK_TAGS.has(tag)
+        if (block) {
+            lineBoundary(state)
+        }
+        // 入れ子表のセル同士は空白 1 つで区切る
+        if (state.mode === "collapse" && (tag === "td" || tag === "th") && state.text !== "" && !/\s$/.test(state.text)) {
+            state.text += " "
+        }
+        if (tag === "a" && state.href === null) {
+            const href = element.getAttribute("href")
+            if (href !== null) {
+                state.href = href
+            }
+        }
+        // exit を先に積み、子は末子から積む (pop 順 = 文書順 — 再帰版と同一の訪問順)
+        stack.push({ kind: "exit", element, before: state.text.length, block })
+        for (let child = element.lastChild; child !== null; child = child.previousSibling) {
+            stack.push({ kind: "enter", node: child })
+        }
+    }
+}
+
+/**
+ * Applies every whole-cell run of the walked state on top of the cell declarations, in capture
+ * (inner → outer) order. A run is whole-cell exactly when nothing outside its window is
+ * non-whitespace — equivalent to the whitespace-normalised text equality `key(run) === key(cell)`
+ * (whitespace collapsing never changes the non-whitespace characters, and a run's text is a
+ * contiguous slice of the cell text), but O(1) per run instead of re-materialising and
+ * re-scanning up to the whole cell text per run: a hostile cell nesting thousands of run tags
+ * around a long string must not cost O(depth × text length) inside the paste handler. An
+ * all-whitespace cell has no whole-cell run. `String.prototype.trim` removes exactly the regex
+ * `\s` class, so the window test matches the normalised-key semantics character for character.
+ * 走査済み状態の全「全体 run」をセル宣言の上へ捕捉順 (内 → 外) に適用する。全体 run とは
+ * 「窓の外に非空白が 1 文字も無い」run のことで、空白正規化キー一致 `key(run) === key(cell)` と
+ * 等価 (空白畳みは非空白文字を増減させず、run の文字列はセル文字列の連続 slice) — ただし run 毎に
+ * セル全文級の文字列を実体化 / 再走査せず 1 run O(1) で判定する: 長文を数千の run タグで包んだ
+ * 敵対セルが paste ハンドラ内で O(深さ × 文字数) の同期費用になってはならない。空白だけのセルに
+ * 全体 run は無い。`String.prototype.trim` の除去集合は正規表現 `\s` と同一なので、窓判定は
+ * 正規化キー意味論と文字単位で一致する。
+ */
+const applyWholeCellRuns = (state: WalkState, declarations: Declarations, flags: RunFlags, rules: StyleRules): void => {
+    // 非空白の範囲は 1 回だけ求める: [first, trimmedLength) — trimmedLength = 最後の非空白の直後
+    const trimmedLength = state.text.trimEnd().length
+    if (trimmedLength === 0) {
+        return
+    }
+    const first = state.text.length - state.text.trimStart().length
+    for (const run of state.runs) {
+        // セル全文 (空白を除く) を窓に含む run だけがセルを書式付けする (部分 run は無視)
+        if (run.before <= first && run.end >= trimmedLength) {
+            applyRun(run.element, declarations, flags, rules)
+        }
+    }
+}
+
+/**
+ * Finishes the walked text per mode: U+00A0 → space everywhere; `pre` verbatim; `pre-line` and
+ * collapse split into lines, runs of spaces / tabs → one space, each line trimmed; collapse also
+ * drops leading / trailing empty lines.
+ * 走査済み文字列をモード毎に仕上げる: U+00A0 → 空白 (全モード)、`pre` は原文、`pre-line` と collapse は
+ * 行毎に空白 / タブの連なりを 1 空白へ畳み trim、collapse は先頭 / 末尾の空行も落とす。
+ */
+const finishText = (raw: string, mode: WhiteSpaceMode): string => {
+    const spaced = raw.replaceAll(NBSP, " ")
+    if (mode === "pre") {
+        return spaced
+    }
+    const lines = spaced.split("\n").map((line) => line.replace(/[ \t\f\r]+/g, " ").trim())
+    if (mode === "pre-line") {
+        return lines.join("\n")
+    }
+    let first = 0
+    while (first < lines.length && lines[first] === "") {
+        first += 1
+    }
+    let last = lines.length
+    while (last > first && lines[last - 1] === "") {
+        last -= 1
+    }
+    return lines.slice(first, last).join("\n")
+}
+
+/**
+ * Applies a whole-cell run element on top of the cell declarations: tag semantics (`b` /
+ * `strong` bold, `i` / `em` italic, `u` underline, `s` / `strike` / `del` line-through, `font`
+ * `color` / `face` attributes) then the run's own class rules and inline style (later wins).
+ * セル宣言の上へ全体 run 要素を適用: タグ意味論 (`b` / `strong` 太字、`i` / `em` 斜体、`u` 下線、
+ * `s` / `strike` / `del` 取消線、`font` の `color` / `face` 属性)、次に run 自身のクラス規則と
+ * インライン style (後勝ち)。
+ */
+const applyRun = (run: Element, declarations: Declarations, flags: RunFlags, rules: StyleRules): void => {
+    const tag = run.localName
+    if (tag === "b" || tag === "strong") {
+        declarations.set("font-weight", "bold")
+    } else if (tag === "i" || tag === "em") {
+        declarations.set("font-style", "italic")
+    } else if (tag === "u") {
+        flags.underline = true
+    } else if (tag === "s" || tag === "strike" || tag === "del") {
+        flags.strikethrough = true
+    } else if (tag === "font") {
+        const color = run.getAttribute("color")
+        const face = run.getAttribute("face")
+        if (color !== null && color.trim() !== "") {
+            declarations.set("color", color)
+        }
+        if (face !== null && face.trim() !== "") {
+            declarations.set("font-family", face)
+        }
+    }
+    mergeDeclarations(declarations, declarationsOf(run, rules))
+}
+
+// ---------------------------------------------------------------------------------------------
+// Reader — values
+// reader — 値
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The typed text of a `data-sheets-value` JSON (object form `{"1":type,"<type>":payload}` or the
+ * 2015 positional array): 2 string, 3 number (a serial → ISO under a date value format), 4
+ * boolean, 5 error sub-code. Null for malformed JSON, an unknown type or a payload of the wrong
+ * shape (a non-finite number, or a date serial outside the grammar's serial domain, included) —
+ * the caller then uses the visible text.
+ * `data-sheets-value` JSON (object 形か 2015 年の位置配列) の型付き文字列: 2 文字列、3 数値 (date
+ * 書式下のシリアルは ISO へ)、4 真偽値、5 エラー副コード。不正 JSON / 未知の型 / 形違いの payload
+ * (非有限や文法シリアル域外の date シリアルを含む) は null — 呼び手は可視文字列を使う。
+ */
+const readSheetsValue = (json: string, value: CellValueFormat | undefined): string | null => {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(json)
+    } catch {
+        // 不正 JSON は「型付き値なし」— 可視文字列へ (全域 fail-soft)
+        return null
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null
+    }
+    const record = parsed as Record<string, unknown>
+    const type = record["1"]
+    if (typeof type !== "number") {
+        return null
+    }
+    const payload = record[String(type)]
+    if (type === 2) {
+        return typeof payload === "string" ? payload : null
+    }
+    if (type === 3) {
+        if (typeof payload !== "number" || !Number.isFinite(payload)) {
+            return null
+        }
+        return value !== undefined && value.type === "date" ? serialToIsoDate(payload) : String(payload)
+    }
+    if (type === 4) {
+        return payload === 1 || payload === true ? "TRUE" : payload === 0 || payload === false ? "FALSE" : null
+    }
+    if (type === 5 && typeof payload === "object" && payload !== null) {
+        const code = (payload as Record<string, unknown>)["1"]
+        return typeof code === "number" && code >= 1 && code < SHEETS_ERROR_TEXT.length ? SHEETS_ERROR_TEXT[code] : null
+    }
+    return null
+}
+
+/** The visible text as a value: canonicalised under a numeric value format, verbatim otherwise. / 可視文字列としての値: 数値書式下は正準化、他は原文。 */
+const displayValue = (text: string, value: CellValueFormat | undefined, separators: NumberSeparators): string => (value !== undefined && isNumericValueFormat(value) ? numberDisplayToCanonical(text, value, separators) : text)
+
+/**
+ * The value text of an Excel / generic cell: `x:str` (its value, or the display when bare),
+ * `x:bool` (TRUE / FALSE), `x:err`, `x:num` (a strict decimal — a serial inside the grammar's
+ * serial domain becomes ISO under a date format; outside it the display text is kept), else the
+ * display text (canonicalised under a numeric format).
+ * Excel / 汎用セルの値文字列: `x:str` (値、裸なら表示)、`x:bool` (TRUE / FALSE)、`x:err`、`x:num`
+ * (厳密 10 進 — date 書式下は文法シリアル域内だけ ISO へ、域外は可視文字列を保つ)、無ければ表示
+ * 文字列 (数値書式下は正準化)。
+ */
+const excelValueText = (cell: Element, text: string, value: CellValueFormat | undefined, separators: NumberSeparators): string => {
+    const str = cell.getAttribute("x:str")
+    if (str !== null) {
+        return str === "" ? text : str
+    }
+    const bool = cell.getAttribute("x:bool")
+    if (bool !== null) {
+        const upper = bool.toUpperCase()
+        return upper === "TRUE" || upper === "FALSE" ? upper : text
+    }
+    const err = cell.getAttribute("x:err")
+    if (err !== null) {
+        return err === "" ? text : err
+    }
+    const num = cell.getAttribute("x:num")
+    if (num !== null && num !== "" && parseNumber(num) !== null) {
+        // parseNumber は有限の 10 進だけを通す — date 書式下ではシリアル
+        if (value !== undefined && value.type === "date") {
+            const iso = serialToIsoDate(Number(num))
+            // 文法シリアル域外 (null) は変換せず可視文字列へ (下の displayValue は date 書式で原文を返す)
+            if (iso !== null) {
+                return iso
+            }
+        } else {
+            return num
+        }
+    }
+    return displayValue(text, value, separators)
+}
+
+// ---------------------------------------------------------------------------------------------
+// Reader — cells, sizes, layout
+// reader — セル・寸法・配置
+// ---------------------------------------------------------------------------------------------
+
+/** One parsed cell: the wire cell and its (possibly empty) format. / 解析済みセル 1 つ: wire セルと (空かもしれない) 書式。 */
+type ReadCell = { readonly cell: ClipCell; readonly format: CellFormat }
+
+/**
+ * Reads one `<td>` / `<th>` at (row, col): declarations (bgcolor < classes < inline), the text
+ * walk, whole-cell runs applied, the CellFormat, then the kind-specific value / formula / link /
+ * note carriers described in the fileoverview.
+ * (row, col) の `<td>` / `<th>` を 1 つ読む: 宣言 (bgcolor < クラス < インライン)、文字列走査、全体
+ * run の適用、CellFormat、次に fileoverview の kind 毎の値 / 数式 / リンク / ノート運搬体。
+ */
+const readCell = (element: Element, row: number, col: number, context: ReadContext): ReadCell => {
+    const declarations = declarationsOf(element, context.rules)
+    const flags: RunFlags = { underline: false, strikethrough: false }
+    const state: WalkState = { text: "", runs: [], href: null, mode: whiteSpaceModeOf(declarations) }
+    for (const child of nodeChildren(element)) {
+        walkCell(child, state)
+    }
+    applyWholeCellRuns(state, declarations, flags, context.rules)
+    const text = finishText(state.text, state.mode)
+    const format = formatFromDeclarations(declarations, flags, context.kind)
+    const cell: ClipCell = { t: "" }
+    if (context.kind === "sheets") {
+        const numberFormat = element.getAttribute("data-sheets-numberformat")
+        const value = numberFormat === null ? undefined : fromSheetsNumberFormat(numberFormat, context.options)
+        if (value !== undefined) {
+            format.value = value
+        }
+        const typedJson = element.getAttribute("data-sheets-value")
+        const typed = typedJson === null ? null : readSheetsValue(typedJson, value)
+        cell.t = typed === null ? displayValue(text, value, DEFAULT_HTML_SEPARATORS) : typed
+        const formula = element.getAttribute("data-sheets-formula")
+        if (formula?.startsWith("=")) {
+            cell.f = formula
+        }
+        const hyperlink = element.getAttribute("data-sheets-hyperlink")
+        // 属性が運搬体 (在れば <a> は見ない)、無ければ最初の <a href>
+        const rawLink = hyperlink !== null ? hyperlink : state.href
+        const link = rawLink === null ? null : normalizeHyperlink(rawLink)
+        if (link !== null) {
+            cell.link = link
+        }
+        const note = element.getAttribute("data-sheets-note")
+        if (note !== null && note !== "") {
+            cell.note = note
+        }
+    } else {
+        const msoFormat = declarations.get("mso-number-format")
+        const value = msoFormat === undefined ? undefined : fromExcelPattern(decodeMsoNumberFormat(stripCssQuotes(msoFormat)), context.options)
+        if (value !== undefined) {
+            format.value = value
+        }
+        cell.t = excelValueText(element, text, value, context.separators)
+        const formula = element.getAttribute("x:fmla")
+        if (formula?.startsWith("=")) {
+            cell.f = toR1C1(formula, { row, col })
+        }
+        const link = state.href === null ? null : normalizeHyperlink(state.href)
+        if (link !== null) {
+            cell.link = link
+        }
+    }
+    return { cell, format }
+}
+
+/** HTML non-negative-integer reading of a span attribute clamped to [1, max] (missing / 0 / garbage ⇒ 1). / span 属性の HTML 非負整数読み ([1, max] へクランプ、欠落 / 0 / 不正は 1)。 */
+const spanOf = (element: Element, name: string, max: number): number => {
+    const raw = element.getAttribute(name)
+    if (raw === null) {
+        return 1
+    }
+    const match = /^\s*\+?(\d+)/.exec(raw)
+    if (match === null) {
+        return 1
+    }
+    const n = Number(match[1])
+    return n < 1 ? 1 : n > max ? max : n
+}
+
+/** A CSS length in px from `Npx` / `Npt` (pt × 4 / 3, rounded), or null. / `Npx` / `Npt` (pt × 4 / 3、丸め) からの px 長、なければ null。 */
+const lengthPx = (value: string): number | null => {
+    const match = /^(\d*\.?\d+)(px|pt)$/i.exec(value.trim())
+    if (match === null) {
+        return null
+    }
+    const n = Number(match[1])
+    return match[2].toLowerCase() === "pt" ? Math.round((n * 4) / 3) : Math.round(n)
+}
+
+/** An HTML dimension attribute (`width=69`) in px, or null. / HTML の寸法属性 (`width=69`) の px、なければ null。 */
+const attributePx = (element: Element, name: string): number | null => {
+    const raw = element.getAttribute(name)
+    if (raw === null) {
+        return null
+    }
+    const match = /^\s*\+?(\d*\.?\d+)/.exec(raw)
+    return match === null ? null : Math.round(Number(match[1]))
+}
+
+/**
+ * A track size in px: `display:none` ⇒ 0; then the style length (`height:36.5pt` is Excel's native
+ * row height, `height:21px` Sheets'); then the HTML attribute (`<col width=69>` is Excel's native
+ * column width). Null when nothing declares it. Every declared size is clamped to
+ * MAX_TRACK_SIZE_PX — foreign HTML is a trust boundary and a hostile width must not wedge the
+ * non-undoable grid geometry (same bound as the resize gate and the wire validator).
+ * トラック寸法 (px): `display:none` は 0、次に style の長さ (`height:36.5pt` は Excel の行高の
+ * 原値、`height:21px` は Sheets)、次に HTML 属性 (`<col width=69>` は Excel の列幅の原値)。無ければ null。
+ * 宣言済み寸法は全て MAX_TRACK_SIZE_PX へクランプ (外来 HTML は信頼境界 — 敵対幅に非 undo の
+ * 格子幾何を破壊させない。リサイズゲート / wire 検証器と同一上限)。
+ */
+const trackSize = (element: Element, property: "width" | "height"): number | null => {
+    const style = element.getAttribute("style")
+    const declarations = style === null ? null : tokenizeInlineStyle(style)
+    if (declarations !== null) {
+        const display = declarations.get("display")
+        if (display !== undefined && display.toLowerCase() === "none") {
+            return 0
+        }
+        const length = declarations.get(property)
+        const px = length === undefined ? null : lengthPx(length)
+        if (px !== null) {
+            return Math.min(px, MAX_TRACK_SIZE_PX)
+        }
+    }
+    const attribute = attributePx(element, property)
+    return attribute === null ? null : Math.min(attribute, MAX_TRACK_SIZE_PX)
+}
+
+/**
+ * Column widths declared by `<col>` elements (direct or in `<colgroup>`), `span` expanded, read
+ * only up to `cols` entries (a run of `<col span=1000>` never materialises beyond the cell columns).
+ * `<col>` (直下 / `<colgroup>` 内) が宣言する列幅 (`span` 展開済み)。`cols` 件までしか読まない
+ * (`<col span=1000>` の連打はセル列数を超えて実体化しない)。
+ */
+const readColumnWidths = (table: Element, cols: number): (number | null)[] => {
+    const widths: (number | null)[] = []
+    const pushCol = (col: Element): void => {
+        const size = trackSize(col, "width")
+        for (let k = spanOf(col, "span", HTML_COLSPAN_MAX); k > 0 && widths.length < cols; k -= 1) {
+            widths.push(size)
+        }
+    }
+    for (const child of elementChildren(table)) {
+        // 列数ぶん揃ったら以後の宣言は読まない
+        if (widths.length >= cols) {
+            break
+        }
+        if (child.localName === "col") {
+            pushCol(child)
+        } else if (child.localName === "colgroup") {
+            for (const col of elementChildren(child)) {
+                if (col.localName === "col" && widths.length < cols) {
+                    pushCol(col)
+                }
+            }
+        }
+    }
+    return widths
+}
+
+/**
+ * The element children of a parent through the sibling links (`firstElementChild` /
+ * `nextElementSibling`) — O(1) a step in every DOM. A live `HTMLCollection` (`children`) resolves
+ * its index on every access, which jsdom answers in O(index): walking a 65,534-row table through
+ * it is quadratic (minutes), through the links it is milliseconds.
+ * 親の要素子を兄弟リンク (`firstElementChild` / `nextElementSibling`) で列挙する — どの DOM でも
+ * 1 歩 O(1)。live な `HTMLCollection` (`children`) は参照毎に添字解決され jsdom では O(添字):
+ * 65,534 行の表を添字で歩くと二次 (分単位)、リンクならミリ秒。
+ */
+function* elementChildren(parent: Element): Generator<Element, undefined, undefined> {
+    for (let child = parent.firstElementChild; child !== null; child = child.nextElementSibling) {
+        yield child
+    }
+}
+
+/** The child nodes (text nodes included) of a node through `firstChild` / `nextSibling` — the `NodeList` counterpart of `elementChildren`. / ノードの子ノード (テキストノード含む) を `firstChild` / `nextSibling` で列挙する — `elementChildren` の `NodeList` 版。 */
+function* nodeChildren(parent: Node): Generator<Node, undefined, undefined> {
+    for (let child = parent.firstChild; child !== null; child = child.nextSibling) {
+        yield child
+    }
+}
+
+/**
+ * The rows of a table in HTML `rows` order — `thead` rows, then direct / `tbody` rows in tree
+ * order, then `tfoot` — yielded lazily (three passes over the table's direct children, one per
+ * section kind) so the reader that stops at its `maxCells` bound never walks the rows behind it.
+ * 表の行を HTML の `rows` 順 — `thead`、直下 / `tbody` の行 (木順)、`tfoot` — で遅延列挙する
+ * (表の直下の子を節種別ごとに 3 回通る): `maxCells` の下界で止まる reader はその先の行を歩かない。
+ */
+function* tableRows(table: Element): Generator<Element, undefined, undefined> {
+    for (const pass of ["thead", "tbody", "tfoot"] as const) {
+        for (const child of elementChildren(table)) {
+            const tag = child.localName
+            if (pass === "tbody" && tag === "tr") {
+                // 直下の tr は tbody の行と同じ通過で木順に混ぜる
+                yield child
+            } else if (tag === pass) {
+                for (const row of elementChildren(child)) {
+                    if (row.localName === "tr") {
+                        yield row
+                    }
+                }
+            }
+        }
+    }
+}
+
+/** A fresh blank cell (covered by a merge or padding a ragged row). / 新規の空白セル (結合に覆われた / ラグ行の詰め物)。 */
+const blankCell = (): ClipCell => ({ t: "" })
+
+/**
+ * The outcome of `parseHtmlTable`: the payload of the first table; `limit` when the table would
+ * materialise more than the caller's `maxCells` (`cells` = the lower bound of `rows × cols` at
+ * which the reader stopped — already above the cap); `none` when there is no table, no row or no
+ * cell column.
+ * `parseHtmlTable` の結果: 最初の表の payload。`limit` は表が呼び手の `maxCells` を超えて実体化する
+ * とき (`cells` = reader が止まった時点の `rows × cols` の下界 — 既に上限超)。`none` は表 / 行 /
+ * セル列が無いとき。
+ */
+export type HtmlTableResult = { readonly outcome: "payload"; readonly payload: ClipPayload } | { readonly outcome: "limit"; readonly cells: number } | { readonly outcome: "none" }
+
+/**
+ * Reads the FIRST table of a parsed document into a payload (see the fileoverview reader
+ * contract), stopping with `limit` as soon as the lower bound of the final `rows × cols` exceeds
+ * `maxCells` — checked BEFORE each allocation, so the reader never holds more than `maxCells`
+ * cells; the rows come lazily from `tableRows`, so the stop also ends the row walk. `none` when
+ * there is no table row or no cell column.
+ * 解析済み文書の最初の表を payload へ読む (fileoverview の reader 契約)。最終 `rows × cols` の
+ * 下界が `maxCells` を超えた時点で `limit` — 各実体化の**前**に検査するので reader が持つセルは
+ * `maxCells` を超えない。行は `tableRows` の遅延列挙なので、停止は行の走査も終える。行がない /
+ * セル列がないときは `none`。
+ */
+const readTable = (table: Element, context: ReadContext, maxCells: number): HtmlTableResult => {
+    const interner = createFormatInterner()
+    const matrix: (ClipCell | undefined)[][] = []
+    const heights: (number | null)[] = []
+    // 上の行の rowspan が各列を何行ぶん覆っているか
+    const pending: number[] = []
+    let cols = 0
+    // 行は遅延列挙: 下界超えの return で以後の行は訪れない
+    for (const rowElement of tableRows(table)) {
+        const r = matrix.length
+        // 行の開始: 下界 (r + 1) × max(cols, 1) が上限を超えるなら持越し空白の実体化前に止める。
+        // max(…, 1) はセル未出現 (cols = 0) の <tr> 爆弾でも行数だけで走査を上限に束ねるため —
+        // 列を 1 つでも得れば上限内で終われない表は同じ下界で止まる (セル無し表は none → limit の
+        // 拒否同士の置換で、行数が上限内の表は挙動不変)
+        const rowBound = (r + 1) * Math.max(cols, 1)
+        if (rowBound > maxCells) {
+            return { outcome: "limit", cells: rowBound }
+        }
+        const row: (ClipCell | undefined)[] = []
+        for (let c = 0; c < pending.length; c += 1) {
+            if (pending[c] > 0) {
+                row[c] = blankCell()
+                pending[c] -= 1
+            }
+        }
+        let cursor = 0
+        for (const child of elementChildren(rowElement)) {
+            const tag = child.localName
+            if (tag !== "td" && tag !== "th") {
+                continue
+            }
+            // 最初の空き列へ置く (HTML 表モデル)
+            while (row[cursor] !== undefined) {
+                cursor += 1
+            }
+            const colspan = spanOf(child, "colspan", HTML_COLSPAN_MAX)
+            const rowspan = spanOf(child, "rowspan", HTML_ROWSPAN_MAX)
+            // このセルを置いた後の下界 (r + 1) × max(cols, 幅) を置く前に検査する
+            const bound = (r + 1) * Math.max(cols, cursor + colspan)
+            if (bound > maxCells) {
+                return { outcome: "limit", cells: bound }
+            }
+            const read = readCell(child, r, cursor, context)
+            const fmt = interner.intern(read.format)
+            if (fmt !== undefined) {
+                read.cell.fmt = fmt
+            }
+            row[cursor] = read.cell
+            for (let k = 1; k < colspan; k += 1) {
+                if (row[cursor + k] === undefined) {
+                    row[cursor + k] = blankCell()
+                }
+            }
+            if (rowspan > 1) {
+                for (let k = 0; k < colspan; k += 1) {
+                    const carry = rowspan - 1
+                    const index = cursor + k
+                    pending[index] = pending[index] === undefined || pending[index] < carry ? carry : pending[index]
+                }
+            }
+            cursor += colspan
+        }
+        if (row.length > cols) {
+            cols = row.length
+        }
+        matrix.push(row)
+        heights.push(trackSize(rowElement, "height"))
+    }
+    if (matrix.length === 0 || cols === 0) {
+        return { outcome: "none" }
+    }
+    // 矩形化: 穴とラグ行の不足分を空白で埋める
+    const cells: ClipCell[][] = matrix.map((row) => {
+        const filled: ClipCell[] = []
+        for (let c = 0; c < cols; c += 1) {
+            const cell = row[c]
+            filled.push(cell === undefined ? blankCell() : cell)
+        }
+        return filled
+    })
+    const widths = readColumnWidths(table, cols)
+    const colWidths = widths.length === cols && widths.every((width) => width !== null) ? widths.map((width) => (width === null ? 0 : width)) : undefined
+    const rowHeights = heights.every((height) => height !== null) ? heights.map((height) => (height === null ? 0 : height)) : undefined
+    const payload: ClipPayload = {
+        v: 1,
+        rows: matrix.length,
+        cols,
+        clipId: newClipId(),
+        formats: [...interner.entries],
+        validations: [],
+        cells,
+        ...(colWidths === undefined ? {} : { colWidths }),
+        ...(rowHeights === undefined ? {} : { rowHeights }),
+        wholeRows: false,
+        wholeCols: false,
+        conditionalFormats: [],
+    }
+    return { outcome: "payload", payload }
+}
+
+/**
+ * Parses an Excel / Sheets / generic HTML clipboard string into a ClipPayload (the fileoverview
+ * reader contract). `kind` is the marker-detected source (`detectClipSource`), `options` the host's
+ * declared currency / locale for number-format decoding, `maxCells` the ADR-12 cap the reader
+ * itself enforces (a positive integer — anything else is a RangeError, an API surface, thrown
+ * before the DOMParser is built). TOTAL fail-soft on the markup: any string yields `payload`,
+ * `limit` or `none` — a blow-up of the ENVIRONMENT's own parser (an engine recursion limit on
+ * pathologically deep nesting) resolves `none` too; a payload is always valid for
+ * `serializeClipPayload`. Callers build the
+ * DOMParser only under the ADR-12 estimate and re-gate the payload's `rows × cols` with their
+ * tiling.
+ * Excel / Sheets / 汎用 HTML のクリップボード文字列を ClipPayload へ解析 (fileoverview の reader 契約)。
+ * `kind` はマーカー検出済みソース (`detectClipSource`)、`options` は数値書式復号用のホスト宣言
+ * (通貨 / locale)、`maxCells` は reader 自身が守る ADR-12 上限 (正整数 — 他は DOMParser 構築前に
+ * RangeError、API 面)。マークアップに対しては全域 fail-soft: 任意の文字列に `payload` / `limit` /
+ * `none` — 環境の parser 自身の破綻 (病的な入れ子深さでのエンジン再帰限界) も `none` に畳む。payload は
+ * 常に `serializeClipPayload` に有効。呼び手は ADR-12 見積もり下でだけ DOMParser
+ * を作り、payload の `rows × cols` をタイル込みで再ゲートする。
+ */
+export const parseHtmlTable = (html: string, kind: HtmlTableKind, options: NumberFormatDecodeOptions, maxCells: number): HtmlTableResult => {
+    if (!Number.isInteger(maxCells) || maxCells <= 0) {
+        throw new RangeError(`[spreadsheet] parseHtmlTable requires a positive integer maxCells, received ${maxCells}`)
+    }
+    let doc: Document
+    try {
+        doc = new DOMParser().parseFromString(html, "text/html")
+    } catch {
+        // 環境の parser 自身の破綻 (深さ等のエンジン限界) も全域 fail-soft 契約に畳む — 読めない表
+        return { outcome: "none" }
+    }
+    const table = doc.querySelector("table")
+    if (table === null) {
+        return { outcome: "none" }
+    }
+    const rules = readStyleRules(doc)
+    return readTable(table, { kind, rules, options, separators: rules.separators }, maxCells)
+}