@aiquants/spreadsheet 0.8.0

package/src/clipboard/numberFormatCodec.ts

@@ -0,0 +1,870 @@
+/**
+ * @fileoverview CellValueFormat ⇄ Excel / Google Sheets number-format pattern codec (v0.8 — the
+ * `text/html` interop channel of ADR-14). Pure, React-free, and TOTAL: every decoder is fail-soft
+ * (an unrepresentable or malformed pattern ⇒ `undefined`, never a throw) and every encoder returns
+ * `null` for a value format Excel cannot express (the writer then omits the property).
+ *
+ * Contract (each clause is mutation-gated in numberFormatCodec.spec.ts):
+ * - Six value-format types map to Excel patterns: number → `0.00` / `#,##0.00`, percent → `0.0%`
+ *   (`scale:false` → the literal form `0.0"%"`, which Excel renders WITHOUT ×100), currency →
+ *   `[$¥-411]#,##0` through a closed LCID table (USD in en-US → the native `"$"#,##0.00`),
+ *   scientific → `0.00E+00`, date → lower-case Excel tokens (`yyyy/MM/dd` ⇄ `yyyy/mm/dd`, the
+ *   month-vs-minute `mm` resolved by Excel's neighbour rule and verified by a decode round trip),
+ *   text → `@`.
+ * - The LCID table is the SINGLE source for currency identity: a `[$sym-lcid]` token resolves
+ *   currency AND locale deterministically (an unknown token ⇒ `undefined`); a bare symbol (no LCID)
+ *   is only ever the host's DECLARED currency (`opts.currency`) — the codec never infers a code
+ *   from a symbol glyph.
+ * - Excel named formats (`General` ⇒ no format, `Fixed`, `Standard`, `Percent`, `Scientific`,
+ *   `Short Date`, …) and Sheets `data-sheets-numberformat` JSON (`{"1":type,"2":pattern}`) decode
+ *   through the same pattern engine.
+ * - `decodeMsoNumberFormat` undoes Excel's CSS-string escaping (`\0022` → `"`, `\\` → `\`, `\X` → X)
+ *   and nothing else, so the pattern engine sees genuine Excel syntax.
+ * - `numberDisplayToCanonical` recovers the raw decimal string from a DISPLAYED number under the
+ *   table's declared separators by pure string math (percent ÷100 and scientific expansion are
+ *   decimal-point shifts, never floating point); anything that is not a recognisable rendering
+ *   returns the display text unchanged.
+ *
+ * CellValueFormat ⇄ Excel / Google Sheets 数値書式パターンのコーデック (v0.8 — ADR-14 の
+ * `text/html` 相互運用経路)。純関数・React 非依存・全域 fail-soft (表現不能 / 不正は `undefined`、
+ * throw しない。エンコード不能は `null` で writer が省略)。6 型 ⇄ パターン、閉じた LCID 表が通貨同一性の
+ * 単一情報源 (`[$記号-LCID]` は通貨 + locale を決定的に解決、裸の記号はホスト宣言 `opts.currency`
+ * のみ)、Excel 名前付き書式と Sheets JSON も同じエンジンで復号、`decodeMsoNumberFormat` は CSS
+ * エスケープ解除だけ、`numberDisplayToCanonical` は表示文字列から素の 10 進を文字列演算で復元。
+ */
+
+import type { CellValueFormat } from "../model/cellFormat.ts"
+
+/**
+ * Host declarations consulted while decoding: `currency` = the code a BARE currency symbol
+ * denotes (undeclared ⇒ such patterns are dropped), `locale` = the rendering locale stamped on
+ * decoded numeric formats (an LCID-tagged currency carries its own locale instead).
+ * 復号時に参照するホスト宣言: `currency` = 裸の通貨記号が指す通貨コード (未宣言なら該当パターンは
+ * 省略)、`locale` = 復号した数値書式へ刻む描画 locale (LCID 付き通貨は自身の locale を持つ)。
+ */
+export type NumberFormatDecodeOptions = { readonly currency?: string; readonly locale?: string }
+
+/**
+ * The separators a displayed number was rendered with (`group` may be empty = no grouping ever
+ * appears; `decimal` is required and must differ from `group`).
+ * 表示数値に使われた区切り (`group` は空可 = 桁区切りなし、`decimal` は必須で `group` と異なること)。
+ */
+export type NumberSeparators = { readonly group: string; readonly decimal: string }
+
+/** One LCID-table row: ISO code, Excel symbol, hex LCID (no leading zeros, lower case), BCP-47 locale, ISO minor-unit digits. / LCID 表の 1 行。 */
+type CurrencyRow = { readonly code: string; readonly symbol: string; readonly lcid: string; readonly locale: string; readonly digits: number }
+
+/**
+ * The closed LCID table. The FIRST row of each code is its home locale, which the encoder emits;
+ * every row decodes. Rows are static ISO 4217 / Windows-LCID facts, not runtime probes.
+ * 閉じた LCID 表。各通貨の先頭行がホーム locale (エンコードが使用)、全行が復号対象。静的事実のみ。
+ */
+const CURRENCY_TABLE: readonly CurrencyRow[] = [
+    { code: "JPY", symbol: "¥", lcid: "411", locale: "ja-JP", digits: 0 },
+    { code: "USD", symbol: "$", lcid: "409", locale: "en-US", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "407", locale: "de-DE", digits: 2 },
+    { code: "GBP", symbol: "£", lcid: "809", locale: "en-GB", digits: 2 },
+    { code: "CNY", symbol: "¥", lcid: "804", locale: "zh-CN", digits: 2 },
+    { code: "KRW", symbol: "₩", lcid: "412", locale: "ko-KR", digits: 0 },
+    { code: "AUD", symbol: "$", lcid: "c09", locale: "en-AU", digits: 2 },
+    { code: "CAD", symbol: "$", lcid: "1009", locale: "en-CA", digits: 2 },
+    { code: "CHF", symbol: "CHF", lcid: "807", locale: "de-CH", digits: 2 },
+    { code: "INR", symbol: "₹", lcid: "4009", locale: "en-IN", digits: 2 },
+    { code: "HKD", symbol: "HK$", lcid: "c04", locale: "zh-HK", digits: 2 },
+    { code: "SGD", symbol: "$", lcid: "1004", locale: "zh-SG", digits: 2 },
+    { code: "TWD", symbol: "NT$", lcid: "404", locale: "zh-TW", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "40c", locale: "fr-FR", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "410", locale: "it-IT", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "c0a", locale: "es-ES", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "413", locale: "nl-NL", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "816", locale: "pt-PT", digits: 2 },
+    { code: "EUR", symbol: "€", lcid: "1809", locale: "en-IE", digits: 2 },
+    { code: "NZD", symbol: "$", lcid: "1409", locale: "en-NZ", digits: 2 },
+    { code: "MXN", symbol: "$", lcid: "80a", locale: "es-MX", digits: 2 },
+    { code: "BRL", symbol: "R$", lcid: "416", locale: "pt-BR", digits: 2 },
+]
+
+/** Builds the canonical Excel currency token `[$sym-lcid]` for a row. / 行の正準通貨トークン。 */
+const currencyToken = (symbol: string, lcid: string): string => `[$${symbol}-${lcid}]`
+
+/** Canonical token → row (every table row). / 正準トークン → 行 (全行)。 */
+const ROW_BY_TOKEN: ReadonlyMap<string, CurrencyRow> = new Map(CURRENCY_TABLE.map((row) => [currencyToken(row.symbol, row.lcid), row]))
+
+/** ISO code → its home row (the first row per code). / 通貨コード → ホーム行 (各コードの先頭行)。 */
+const HOME_ROW_BY_CODE: ReadonlyMap<string, CurrencyRow> = new Map(CURRENCY_TABLE.filter((row, index) => CURRENCY_TABLE.findIndex((other) => other.code === row.code) === index).map((row) => [row.code, row]))
+
+/**
+ * Excel currency token `[$¥-411]` → ISO code ("JPY"). Keys are canonical (lower-case hex without
+ * leading zeros); `fromExcelPattern` normalises incoming tokens before the lookup.
+ * Excel 通貨トークン → ISO コード。キーは正準形 (小文字 hex・先頭 0 なし)、復号側で正規化して照会。
+ */
+export const LCID_CURRENCY: ReadonlyMap<string, string> = new Map(CURRENCY_TABLE.map((row) => [currencyToken(row.symbol, row.lcid), row.code]))
+
+/**
+ * Literals that may stand for a currency without an LCID (table symbols, ISO codes, and the
+ * full-width yen that Japanese Excel emits). Any other literal is a unit / caption ⇒ unrepresentable.
+ * LCID なしで通貨を表し得るリテラル (表の記号・ISO コード・日本語 Excel の全角円)。他は単位 / 見出し。
+ */
+const CURRENCY_LITERALS: ReadonlySet<string> = new Set([...CURRENCY_TABLE.map((row) => row.symbol), ...CURRENCY_TABLE.map((row) => row.code), "￥"])
+
+/** Fraction-digit ceiling the encoder accepts (the display engine's guaranteed Intl maximum). / エンコーダが受理する小数桁上限 (表示エンジンの Intl 保証最大)。 */
+const MAX_DECIMALS = 20
+
+/** The display engine's date pattern when `pattern` is absent (mirrors formatCellValue). / `pattern` 省略時の表示エンジン既定 (formatCellValue と同値)。 */
+const DEFAULT_DATE_PATTERN = "yyyy/MM/dd"
+
+/** The package date-token grammar (the exact alternation formatCellValue substitutes). / パッケージの日付トークン文法 (formatCellValue と同一の選択肢)。 */
+const PACKAGE_DATE_TOKEN = /yyyy|MM|dd|HH|mm|ss/g
+
+/** Characters Excel accepts unquoted inside a pattern (literal spacing / punctuation). / Excel が引用なしで受理する文字 (空白 / 句読点)。 */
+const BARE_LITERAL_CHARS = " -+/():!^&'~{}<>="
+
+/** Unquoted currency glyphs Excel renders literally. / Excel が引用なしでそのまま描画する通貨記号。 */
+const BARE_CURRENCY_CHARS = "$¥€£₩₹￥"
+
+/**
+ * Undoes the CSS-string escaping Excel applies to `mso-number-format` values: `\` + exactly four
+ * hex digits → that code point (`\0022` → `"`), `\` + any other character → that character
+ * (`\\` → `\`, `\#` → `#`), a lone trailing `\` stays. Input is the property value WITHOUT its
+ * surrounding CSS quotes; the output is genuine Excel pattern syntax.
+ * Excel が `mso-number-format` 値に施す CSS 文字列エスケープを解除: `\` + hex 4 桁 → その符号位置、
+ * `\` + 他 1 文字 → その文字、末尾の孤立 `\` はそのまま。入力は外側の CSS 引用符を除いた値。
+ */
+export const decodeMsoNumberFormat = (raw: string): string => {
+    let out = ""
+    let i = 0
+    while (i < raw.length) {
+        const c = raw[i]
+        if (c !== "\\") {
+            out += c
+            i += 1
+            continue
+        }
+        // 4 桁 hex エスケープ (\0022 = ") — Excel は常に 4 桁で書く
+        const hex = raw.slice(i + 1, i + 5)
+        if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+            out += String.fromCharCode(Number.parseInt(hex, 16))
+            i += 5
+            continue
+        }
+        // 単一文字エスケープ (\\ → \, \# → #)。末尾の孤立 \ は素通し
+        if (i + 1 < raw.length) {
+            out += raw[i + 1]
+            i += 2
+            continue
+        }
+        out += c
+        i += 1
+    }
+    return out
+}
+
+/** One lexical token of an Excel pattern section. / Excel パターン節の字句トークン。 */
+type PatternToken =
+    | { readonly kind: "digits"; readonly text: string }
+    | { readonly kind: "literal"; readonly text: string }
+    | { readonly kind: "currency"; readonly symbol: string; readonly lcid: string | null }
+    | { readonly kind: "locale" }
+    | { readonly kind: "percent" }
+    | { readonly kind: "exponent" }
+    | { readonly kind: "date"; readonly text: string }
+
+/**
+ * Returns the first `;`-section of a pattern (the positive section) — the separator is honoured
+ * only outside quotes, brackets and escapes. The remaining sections (negative / zero / text) are
+ * dropped: the package renders negatives with a sign, never with colour or parentheses.
+ * パターンの先頭節 (正数節) を返す。区切りは引用 / 角括弧 / エスケープの外だけ有効。残りの節は捨てる。
+ */
+const firstSection = (pattern: string): string => {
+    let i = 0
+    while (i < pattern.length) {
+        const c = pattern[i]
+        if (c === '"') {
+            // 閉じ引用まで読み飛ばす (未終端なら末尾まで = 節全体)
+            const close = pattern.indexOf('"', i + 1)
+            i = close < 0 ? pattern.length : close + 1
+        } else if (c === "[") {
+            const close = pattern.indexOf("]", i + 1)
+            i = close < 0 ? pattern.length : close + 1
+        } else if (c === "\\" || c === "_" || c === "*") {
+            i += 2
+        } else if (c === ";") {
+            return pattern.slice(0, i)
+        } else {
+            i += 1
+        }
+    }
+    return pattern
+}
+
+/**
+ * Tokenises one section of GENUINE Excel syntax; `null` on any construct the codec does not
+ * model (unterminated quote, colour / condition / elapsed-time brackets, dangling escape,
+ * non-literal bare characters). Adjacent literals are merged.
+ * 真の Excel 構文の 1 節を字句解析。未終端引用 / 色・条件・経過時間の角括弧 / 末尾エスケープ /
+ * リテラル不可の裸文字は `null`。隣接リテラルは結合する。
+ */
+const tokenizeSection = (section: string): readonly PatternToken[] | null => {
+    const tokens: PatternToken[] = []
+    // 隣接するリテラルを 1 トークンへ結合 (前置 / 後置の判定を単純にする)
+    const pushLiteral = (text: string): void => {
+        const last = tokens[tokens.length - 1]
+        if (last !== undefined && last.kind === "literal") {
+            tokens[tokens.length - 1] = { kind: "literal", text: last.text + text }
+        } else {
+            tokens.push({ kind: "literal", text })
+        }
+    }
+    let i = 0
+    while (i < section.length) {
+        const c = section[i]
+        if (c === '"') {
+            const close = section.indexOf('"', i + 1)
+            if (close < 0) {
+                return null
+            }
+            pushLiteral(section.slice(i + 1, close))
+            i = close + 1
+        } else if (c === "\\") {
+            // 真の Excel エスケープ: 次の 1 文字がリテラル
+            if (i + 1 >= section.length) {
+                return null
+            }
+            pushLiteral(section[i + 1])
+            i += 2
+        } else if (c === "_" || c === "*") {
+            // 幅合わせ (_X) / 充填 (*X) は列内の詰め物だけ — パッケージは表現しないため落とす
+            if (i + 1 >= section.length) {
+                return null
+            }
+            i += 2
+        } else if (c === "[") {
+            const close = section.indexOf("]", i + 1)
+            const inner = close < 0 ? "" : section.slice(i + 1, close)
+            if (close < 0 || inner[0] !== "$") {
+                return null
+            }
+            // [$記号-LCID] / [$記号] / [$-LCID]: 最後の "-" が記号と LCID を分ける
+            const body = inner.slice(1)
+            const dash = body.lastIndexOf("-")
+            const symbol = dash < 0 ? body : body.slice(0, dash)
+            const lcidRaw = dash < 0 ? null : body.slice(dash + 1)
+            if (lcidRaw !== null && !/^[0-9a-fA-F]{1,8}$/.test(lcidRaw)) {
+                return null
+            }
+            if (symbol === "" && lcidRaw === null) {
+                return null
+            }
+            const lcid = lcidRaw === null ? null : Number.parseInt(lcidRaw, 16).toString(16)
+            tokens.push(symbol === "" ? { kind: "locale" } : { kind: "currency", symbol, lcid })
+            i = close + 1
+        } else if (c === "%") {
+            tokens.push({ kind: "percent" })
+            i += 1
+        } else if ("#0?,.".includes(c)) {
+            let j = i
+            while (j < section.length && "#0?,.".includes(section[j])) {
+                j += 1
+            }
+            // # 0 ? を含む連なりだけが桁構造。"." / "," だけの連なりは区切りリテラル (dd.mm.yyyy 等)
+            const run = section.slice(i, j)
+            if (/[#0?]/.test(run)) {
+                tokens.push({ kind: "digits", text: run })
+            } else {
+                pushLiteral(run)
+            }
+            i = j
+        } else if (/[A-Za-z]/.test(c)) {
+            if ((c === "E" || c === "e") && (section[i + 1] === "+" || section[i + 1] === "-")) {
+                // 指数記号は E+ / E- の後に 0 が 1 個以上
+                let j = i + 2
+                while (section[j] === "0") {
+                    j += 1
+                }
+                if (j === i + 2) {
+                    return null
+                }
+                tokens.push({ kind: "exponent" })
+                i = j
+            } else {
+                // 日付トークン = 同一文字 (大小同一視) の連なり
+                let j = i
+                while (j < section.length && section[j].toLowerCase() === c.toLowerCase()) {
+                    j += 1
+                }
+                tokens.push({ kind: "date", text: section.slice(i, j).toLowerCase() })
+                i = j
+            }
+        } else if (BARE_LITERAL_CHARS.includes(c) || BARE_CURRENCY_CHARS.includes(c) || c.charCodeAt(0) >= 0x80) {
+            pushLiteral(c)
+            i += 1
+        } else {
+            return null
+        }
+    }
+    return tokens
+}
+
+/** `{ locale }` when declared, `{}` otherwise — keeps decoded formats free of `locale: undefined` keys. / 宣言時のみ `locale` キーを持たせる。 */
+const localeField = (locale: string | undefined): { locale?: string } => (locale === undefined ? {} : { locale })
+
+/** Digit structure the package can render: `0` or `#,##0`, optionally with a fixed `0`-run fraction. / パッケージが描画できる桁構造。 */
+const DIGIT_STRUCTURE = /^(0|#,##0)(?:\.(0+))?$/
+
+/**
+ * Resolves a currency: an LCID-tagged token through the closed table (currency AND locale from the
+ * row — an unknown token is unrepresentable), a bare symbol ONLY as the host's declared currency
+ * (`opts.currency`) and only when the literal is a currency literal (a unit suffix never is).
+ * 通貨の解決: LCID 付きトークンは閉じた表 (通貨 + locale を行から。未知は表現不能)、裸の記号は
+ * ホスト宣言 `opts.currency` に限り、かつ通貨リテラル集合の要素だけ (単位の後置は通貨ではない)。
+ */
+const decodeCurrency = (symbol: string, lcid: string | null, decimals: number, opts: NumberFormatDecodeOptions): CellValueFormat | undefined => {
+    if (lcid !== null) {
+        const row = ROW_BY_TOKEN.get(currencyToken(symbol, lcid))
+        return row === undefined ? undefined : { type: "currency", currency: row.code, decimals, locale: row.locale }
+    }
+    // 記号から通貨を推定しない — 宣言がなければ省略
+    if (!CURRENCY_LITERALS.has(symbol) || opts.currency === undefined) {
+        return undefined
+    }
+    return { type: "currency", currency: opts.currency, decimals, ...localeField(opts.locale) }
+}
+
+/**
+ * Decodes a numeric section (one digit structure, optional `%` / exponent / currency token /
+ * one-sided literal). Grouping on percent and currency is accepted and dropped (those package
+ * types carry no grouping flag); every other extra construct is unrepresentable.
+ * 数値節の復号 (桁構造 1 つ + 任意の % / 指数 / 通貨トークン / 片側リテラル)。percent / currency の
+ * 桁区切りは受理して落とす (両型に grouping は無い)。他の余分な構成は表現不能。
+ */
+const decodeNumericSection = (tokens: readonly PatternToken[], opts: NumberFormatDecodeOptions): CellValueFormat | undefined => {
+    let digits = ""
+    let digitsSeen = false
+    let currency: { readonly symbol: string; readonly lcid: string | null } | null = null
+    let exponent = false
+    let percentSigns = 0
+    let prefix = ""
+    let suffix = ""
+    for (const token of tokens) {
+        switch (token.kind) {
+            case "locale":
+                // [$-LCID] 単独の locale タグは無視 — 描画 locale はホスト宣言が決める
+                break
+            case "literal":
+                if (digitsSeen) {
+                    suffix += token.text
+                } else {
+                    prefix += token.text
+                }
+                break
+            case "digits":
+                if (digitsSeen) {
+                    return undefined
+                }
+                digits = token.text
+                digitsSeen = true
+                break
+            case "currency":
+                if (currency !== null) {
+                    return undefined
+                }
+                currency = token
+                break
+            case "percent":
+                percentSigns += 1
+                break
+            case "exponent":
+                if (exponent || !digitsSeen) {
+                    return undefined
+                }
+                exponent = true
+                break
+            default:
+                // 数値節の中の日付トークンは表現不能
+                return undefined
+        }
+    }
+    const structure = DIGIT_STRUCTURE.exec(digits)
+    if (structure === null) {
+        return undefined
+    }
+    const grouping = structure[1] === "#,##0"
+    const decimals = structure[2] === undefined ? 0 : structure[2].length
+    const before = prefix.trim()
+    const after = suffix.trim()
+    // 指数: 桁区切り / % / 通貨 / リテラルのいずれも伴えない
+    if (exponent) {
+        return percentSigns === 0 && currency === null && !grouping && before === "" && after === "" ? { type: "scientific", decimals, ...localeField(opts.locale) } : undefined
+    }
+    // % 記号 (×100 描画) はちょうど 1 つ、他の装飾なし
+    if (percentSigns > 0) {
+        return percentSigns === 1 && currency === null && before === "" && after === "" ? { type: "percent", decimals, ...localeField(opts.locale) } : undefined
+    }
+    // 後置リテラル "%" は ×100 しない percent (値が既に百分率)
+    if (after === "%" && before === "" && currency === null) {
+        return { type: "percent", decimals, scale: false, ...localeField(opts.locale) }
+    }
+    if (currency !== null) {
+        return before === "" && after === "" ? decodeCurrency(currency.symbol, currency.lcid, decimals, opts) : undefined
+    }
+    // 片側のリテラルだけが裸の通貨記号候補 (両側は表現不能)
+    if (before !== "" && after !== "") {
+        return undefined
+    }
+    if (before !== "" || after !== "") {
+        return decodeCurrency(before + after, null, decimals, opts)
+    }
+    return { type: "number", decimals, ...(grouping ? { grouping: true } : {}), ...localeField(opts.locale) }
+}
+
+/** Excel date token → package token for the unambiguous tokens (`mm` is resolved by the neighbour rule). / 曖昧でない日付トークンの写像 (`mm` は隣接規則)。 */
+const EXCEL_DATE_TOKEN: ReadonlyMap<string, string> = new Map([
+    ["yyyy", "yyyy"],
+    ["dd", "dd"],
+    ["hh", "HH"],
+    ["ss", "ss"],
+])
+
+/**
+ * Verifies the package scanner reads back exactly the intended tokens at the intended offsets —
+ * a literal containing a token (`"dd"`) or a literal + token boundary forming one would make
+ * formatCellValue substitute where Excel showed text.
+ * パッケージの走査が意図したトークンを意図した位置で読み戻すことを検証 — リテラル内のトークンや
+ * 境界で生じるトークンは formatCellValue の置換を誤らせる。
+ */
+const packageTokensMatch = (pattern: string, expected: readonly { readonly index: number; readonly text: string }[]): boolean => {
+    const found = [...pattern.matchAll(PACKAGE_DATE_TOKEN)]
+    return found.length === expected.length && found.every((match, k) => match.index === expected[k].index && match[0] === expected[k].text)
+}
+
+/**
+ * Decodes a date section: `yyyy` / `dd` / `hh` / `ss` map directly, `mm` is minutes when the
+ * neighbouring date token is `hh` before or `ss` after (Excel's rule) else month; separators and
+ * quoted literals pass through; any other token (`m`, `yy`, `mmm`, `AM/PM`, digits) is unrepresentable.
+ * 日付節の復号: `yyyy` / `dd` / `hh` / `ss` は直写、`mm` は隣接する日付トークンが前 `hh` か後 `ss` なら
+ * 分・それ以外は月 (Excel の規則)、区切りと引用リテラルは素通し、他のトークンは表現不能。
+ */
+const decodeDateSection = (tokens: readonly PatternToken[]): CellValueFormat | undefined => {
+    const dateTexts = tokens.flatMap((token) => (token.kind === "date" ? [token.text] : []))
+    const expected: { readonly index: number; readonly text: string }[] = []
+    let pattern = ""
+    let dateIndex = 0
+    for (const token of tokens) {
+        if (token.kind === "locale") {
+            continue
+        }
+        if (token.kind === "literal") {
+            pattern += token.text
+            continue
+        }
+        if (token.kind !== "date") {
+            return undefined
+        }
+        // mm の月 / 分は隣接する日付トークンで決まる (間の区切りは無視)
+        const mapped = token.text === "mm" ? (dateTexts[dateIndex - 1] === "hh" || dateTexts[dateIndex + 1] === "ss" ? "mm" : "MM") : EXCEL_DATE_TOKEN.get(token.text)
+        dateIndex += 1
+        if (mapped === undefined) {
+            return undefined
+        }
+        expected.push({ index: pattern.length, text: mapped })
+        pattern += mapped
+    }
+    return expected.length > 0 && packageTokensMatch(pattern, expected) ? { type: "date", pattern } : undefined
+}
+
+/**
+ * Excel named formats (exact spelling). `General` and `@` are the two non-pattern spellings;
+ * `Currency` follows the bare-symbol rule (declared currency only); `Short Date` / `Short Time` are
+ * declared dates whose exact rendering is locale-bound, so they map to the package's default date
+ * rendering / `HH:mm`. Names absent here (`Medium Date`, `Long Time`, `Yes/No`, …) fall through to
+ * the tokenizer, where they are unrepresentable.
+ * Excel 名前付き書式 (綴り厳密)。`Currency` は裸記号規則 (宣言通貨のみ)、`Short Date` / `Short Time`
+ * は描画が locale 依存の宣言済み日付 → パッケージ既定 / `HH:mm`。未掲載名は字句解析で表現不能。
+ */
+/** A named-format decoder (named formats depend on the host declarations). / 名前付き書式の復号器 (ホスト宣言に依存)。 */
+type NamedDecoder = (opts: NumberFormatDecodeOptions) => CellValueFormat | undefined
+const NAMED_FORMATS: ReadonlyMap<string, NamedDecoder> = new Map<string, NamedDecoder>([
+    ["General", () => undefined],
+    ["@", () => ({ type: "text" })],
+    ["Fixed", (opts) => ({ type: "number", decimals: 2, ...localeField(opts.locale) })],
+    ["Standard", (opts) => ({ type: "number", decimals: 2, grouping: true, ...localeField(opts.locale) })],
+    ["Percent", (opts) => ({ type: "percent", decimals: 2, ...localeField(opts.locale) })],
+    ["Scientific", (opts) => ({ type: "scientific", decimals: 2, ...localeField(opts.locale) })],
+    ["Currency", (opts) => (opts.currency === undefined ? undefined : { type: "currency", currency: opts.currency, decimals: 2, ...localeField(opts.locale) })],
+    ["Euro Currency", (opts) => ({ type: "currency", currency: "EUR", decimals: 2, ...localeField(opts.locale) })],
+    ["Short Date", () => ({ type: "date" })],
+    ["Short Time", () => ({ type: "date", pattern: "HH:mm" })],
+])
+
+/**
+ * Decodes an Excel / Sheets pattern (GENUINE syntax — run decodeMsoNumberFormat first for
+ * `mso-number-format` values) into a CellValueFormat. TOTAL: named formats, the first `;`
+ * section of a custom pattern, currency via the LCID table or the declared bare currency,
+ * dates via the token grammar; anything else (or `General`) ⇒ `undefined`. Never throws.
+ * Excel / Sheets パターン (真の構文 — `mso-number-format` 値は先に decodeMsoNumberFormat) を
+ * CellValueFormat へ復号。全域: 名前付き書式、カスタムの先頭節、LCID 表または宣言通貨の裸記号、
+ * トークン文法の日付。それ以外 (と `General`) は `undefined`。throw しない。
+ */
+export const fromExcelPattern = (pattern: string, opts: NumberFormatDecodeOptions): CellValueFormat | undefined => {
+    const section = firstSection(pattern).trim()
+    const named = NAMED_FORMATS.get(section)
+    if (named !== undefined) {
+        return named(opts)
+    }
+    const tokens = tokenizeSection(section)
+    if (tokens === null) {
+        return undefined
+    }
+    // 桁構造があれば数値節、日付トークンだけなら日付節、どちらも無ければ (リテラルのみ) 表現不能
+    if (tokens.some((token) => token.kind === "digits")) {
+        return decodeNumericSection(tokens, opts)
+    }
+    if (tokens.some((token) => token.kind === "date")) {
+        return decodeDateSection(tokens)
+    }
+    return undefined
+}
+
+/**
+ * Decodes a Sheets `data-sheets-numberformat` JSON value (`{"1":type,"2":pattern}`; the entity
+ * decoding is the caller's). Type codes: 0 automatic ⇒ no format, 1 TEXT ⇒ text, 5 DATE ⇒ the
+ * pattern when representable else the default date rendering (the type declares date-ness), and
+ * 2 NUMBER / 3 PERCENT / 4 CURRENCY / 6 TIME / 7 DATE_TIME / 8 SCIENTIFIC ⇒ the pattern (the
+ * pattern is the source of truth for rendering). Malformed JSON / shape / code ⇒ `undefined`.
+ * Sheets の `data-sheets-numberformat` JSON を復号 (実体復号は呼び出し側)。型コード 0 は書式なし、
+ * 1 はテキスト、5 は表現可能ならパターン・不能なら既定日付描画 (型が日付性を宣言)、他はパターンが
+ * 描画の真実の源。不正な JSON / 形 / コードは `undefined`。
+ */
+export const fromSheetsNumberFormat = (json: string, opts: NumberFormatDecodeOptions): CellValueFormat | undefined => {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(json)
+    } catch {
+        // 不正 JSON は「書式なし」— 全域 fail-soft の契約 (値の代替ではなく省略)
+        return undefined
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return undefined
+    }
+    const record = parsed as Record<string, unknown>
+    const type = record["1"]
+    const pattern = record["2"]
+    if (typeof type !== "number" || !Number.isInteger(type) || type < 0 || type > 8) {
+        return undefined
+    }
+    if (pattern !== undefined && typeof pattern !== "string") {
+        return undefined
+    }
+    if (type === 0) {
+        return undefined
+    }
+    if (type === 1) {
+        return { type: "text" }
+    }
+    const decoded = pattern === undefined ? undefined : fromExcelPattern(pattern, opts)
+    // DATE (5) は pattern が表現不能でも日付であることが宣言済み — 既定描画の date へ
+    if (type === 5) {
+        return decoded !== undefined && decoded.type === "date" ? decoded : { type: "date" }
+    }
+    return decoded
+}
+
+/** `.00`-style fraction placeholders for a decimals count (empty for 0). / 小数桁のプレースホルダ。 */
+const fractionPattern = (decimals: number): string => (decimals === 0 ? "" : `.${"0".repeat(decimals)}`)
+
+/** A decimals count Excel and the display engine both accept (integer 0..20). / Excel と表示エンジン双方が受理する小数桁数。 */
+const isValidDecimals = (decimals: number | undefined): decimals is number => decimals !== undefined && Number.isInteger(decimals) && decimals >= 0 && decimals <= MAX_DECIMALS
+
+/** Chars the encoder leaves unquoted inside a date section. / 日付節でエンコーダが引用しない文字。 */
+const BARE_DATE_LITERAL_CHARS = `${BARE_LITERAL_CHARS}.,`
+
+/**
+ * Quotes a package date literal for Excel: separators / spacing stay bare, anything else (e.g.
+ * 年 月 日) is wrapped in quotes; a literal containing `"` is unrepresentable.
+ * パッケージ日付リテラルの Excel 化: 区切り / 空白は裸、他 (年 月 日 等) は引用で包む。`"` を含めば表現不能。
+ */
+const quoteDateLiteral = (literal: string): string | null => {
+    if (literal.includes('"')) {
+        return null
+    }
+    return [...literal].every((c) => BARE_DATE_LITERAL_CHARS.includes(c)) ? literal : `"${literal}"`
+}
+
+/**
+ * Encodes a package date pattern: each token lower-cased (`MM` → `mm`, `HH` → `hh` — Excel's
+ * spelling), literals quoted as needed, then VERIFIED by decoding back — a pattern Excel would read
+ * differently (a minutes-only `mm`, which Excel reads as month) is unrepresentable.
+ * パッケージ日付パターンのエンコード: トークン小文字化、リテラルは必要に応じ引用、復号して往復検証 —
+ * Excel が別読みする形 (分だけの `mm` は月と読まれる) は表現不能。
+ */
+const encodeDatePattern = (pattern: string): string | null => {
+    const parts: string[] = []
+    let tokenCount = 0
+    let last = 0
+    for (const match of pattern.matchAll(PACKAGE_DATE_TOKEN)) {
+        const literal = quoteDateLiteral(pattern.slice(last, match.index))
+        if (literal === null) {
+            return null
+        }
+        parts.push(literal, match[0].toLowerCase())
+        tokenCount += 1
+        last = match.index + match[0].length
+    }
+    const tail = quoteDateLiteral(pattern.slice(last))
+    if (tail === null || tokenCount === 0) {
+        return null
+    }
+    parts.push(tail)
+    const excel = parts.join("")
+    // 往復検証 — Excel の隣接規則で月 / 分が入れ替わる形は表現不能
+    const back = fromExcelPattern(excel, {})
+    return back !== undefined && back.type === "date" && back.pattern === pattern ? excel : null
+}
+
+/**
+ * Encodes a currency format through the home row of its code (`decimals` absent ⇒ the ISO minor
+ * units, which is what the display engine renders). USD in en-US is written in the native quoted
+ * form `"$"#,##0.00` that Excel / Sheets recognise as their own currency; every other case carries
+ * the LCID token. A code outside the table is unrepresentable.
+ * 通貨書式のエンコード (ホーム行、`decimals` 省略は ISO 補助単位 = 表示エンジンの描画)。en-US の
+ * USD だけは Excel / Sheets が自国通貨と認識する `"$"#,##0.00`、他は LCID トークン。表外の通貨は表現不能。
+ */
+const encodeCurrency = (value: { readonly currency: string; readonly decimals?: number; readonly locale?: string }): string | null => {
+    const row = HOME_ROW_BY_CODE.get(value.currency.toUpperCase())
+    if (row === undefined) {
+        return null
+    }
+    const decimals = value.decimals === undefined ? row.digits : value.decimals
+    if (!isValidDecimals(decimals)) {
+        return null
+    }
+    const digits = `#,##0${fractionPattern(decimals)}`
+    return row.code === "USD" && value.locale === "en-US" ? `"$"${digits}` : `${currencyToken(row.symbol, row.lcid)}${digits}`
+}
+
+/**
+ * Encodes a CellValueFormat as an Excel / Sheets pattern; `null` when Excel cannot express it
+ * (a `number` / `scientific` without fixed decimals — Excel has no "as many digits as needed"
+ * without a dangling point — an out-of-range decimals count, a currency outside the LCID table,
+ * a date pattern Excel would read differently). `percent` without decimals is exactly `0%`.
+ * CellValueFormat を Excel / Sheets パターンへ。表現不能は `null` (小数桁未固定の number /
+ * scientific、範囲外の小数桁、表外通貨、Excel が別読みする日付)。decimals 省略の percent は厳密に `0%`。
+ */
+export const toExcelPattern = (value: CellValueFormat): string | null => {
+    switch (value.type) {
+        case "text":
+            return "@"
+        case "date":
+            return encodeDatePattern(value.pattern === undefined ? DEFAULT_DATE_PATTERN : value.pattern)
+        case "number":
+            return isValidDecimals(value.decimals) ? `${value.grouping === true ? "#,##0" : "0"}${fractionPattern(value.decimals)}` : null
+        case "percent": {
+            // decimals 省略 = Intl の percent 既定 (小数 0 桁) と厳密に等価
+            const decimals = value.decimals === undefined ? 0 : value.decimals
+            if (!isValidDecimals(decimals)) {
+                return null
+            }
+            // scale:false は値が既に百分率 — Excel の "%" リテラル (×100 なし) で表す
+            return value.scale === false ? `0${fractionPattern(decimals)}"%"` : `0${fractionPattern(decimals)}%`
+        }
+        case "scientific":
+            return isValidDecimals(value.decimals) ? `0${fractionPattern(value.decimals)}E+00` : null
+        case "currency":
+            return encodeCurrency(value)
+        default: {
+            // 到達不能 (6 型を網羅) — 将来の型追加を型エラーで検出しつつ実行時は表現不能
+            const exhaustive: never = value
+            void exhaustive
+            return null
+        }
+    }
+}
+
+/** The minus glyphs a rendering may carry (ASCII hyphen-minus, U+2212). / 描画が持ち得るマイナス記号。 */
+const MINUS_SIGNS = "-−"
+
+/** A display core split into digit strings plus an exponent (string math only). / 表示核の分解 (文字列演算のみ)。 */
+type DisplayCore = { readonly integer: string; readonly fraction: string; readonly exponent: number }
+
+/**
+ * Removes a group separator from an integer digit string, requiring Excel's structure (1-3 leading
+ * digits, then groups of exactly 3) so a stray separator never silently merges digits; without a
+ * separator the string must be plain digits. `null` otherwise.
+ * 整数桁文字列から桁区切りを除く。Excel の構造 (先頭 1-3 桁 + 3 桁組) を要求し、迷い込んだ区切りで
+ * 桁を黙って併合しない。区切りなしなら素の数字列。それ以外は `null`。
+ */
+const ungroupDigits = (integerText: string, group: string): string | null => {
+    if (group === "" || !integerText.includes(group)) {
+        return /^\d+$/.test(integerText) ? integerText : null
+    }
+    const chunks = integerText.split(group)
+    if (!/^\d{1,3}$/.test(chunks[0]) || chunks.slice(1).some((chunk) => !/^\d{3}$/.test(chunk))) {
+        return null
+    }
+    return chunks.join("")
+}
+
+/**
+ * Parses the digit core of a rendering: optional exponent (`required` for scientific, `optional`
+ * for General, `none` otherwise), at most one decimal separator, digit-only fraction, grouped
+ * integer per ungroupDigits. `null` when the core is not a rendering.
+ * 描画の数字核を解析: 指数 (scientific は必須、General は任意、他は不可)、小数区切りは高々 1 つ、
+ * 小数部は数字のみ、整数部は ungroupDigits。描画でなければ `null`。
+ */
+const parseDisplayCore = (core: string, group: string, decimal: string, exponentMode: "required" | "optional" | "none"): DisplayCore | null => {
+    const exponentMatch = /^(.*?)[eE]([+-]?\d{1,4})$/.exec(core)
+    if (exponentMatch !== null && exponentMode === "none") {
+        return null
+    }
+    if (exponentMatch === null && exponentMode === "required") {
+        return null
+    }
+    const mantissa = exponentMatch === null ? core : exponentMatch[1]
+    const exponent = exponentMatch === null ? 0 : Number(exponentMatch[2])
+    const parts = mantissa.split(decimal)
+    if (parts.length > 2) {
+        return null
+    }
+    const fraction = parts.length === 2 ? parts[1] : ""
+    if (parts.length === 2 && !/^\d+$/.test(fraction)) {
+        return null
+    }
+    const integer = ungroupDigits(parts[0], group)
+    return integer === null ? null : { integer, fraction, exponent }
+}
+
+/**
+ * Builds the canonical decimal string from digit strings, a decimal-point shift (exponent and
+ * percent ÷100 combined) and a sign — pure string math: leading zeros trimmed, trailing fraction
+ * zeros trimmed, and never a negative zero.
+ * 桁文字列・小数点シフト (指数と percent ÷100 の合算)・符号から正準 10 進文字列を組む — 純文字列演算。
+ * 先頭 0 と小数末尾 0 を除き、負ゼロは作らない。
+ */
+const canonicalDecimal = (integer: string, fraction: string, shift: number, negative: boolean): string => {
+    const digits = integer + fraction
+    const point = integer.length + shift
+    let intPart: string
+    let fracPart: string
+    if (point <= 0) {
+        intPart = "0"
+        fracPart = "0".repeat(-point) + digits
+    } else if (point >= digits.length) {
+        intPart = digits + "0".repeat(point - digits.length)
+        fracPart = ""
+    } else {
+        intPart = digits.slice(0, point)
+        fracPart = digits.slice(point)
+    }
+    intPart = intPart.replace(/^0+(?=\d)/, "")
+    fracPart = fracPart.replace(/0+$/, "")
+    const magnitude = fracPart === "" ? intPart : `${intPart}.${fracPart}`
+    return negative && magnitude !== "0" ? `-${magnitude}` : magnitude
+}
+
+/**
+ * Recovers the raw canonical decimal string from a DISPLAYED number under the declared
+ * separators: grouping removed ("2,728,548" → "2728548"), percent divided by 100 by a
+ * decimal-point shift ("20%" → "0.2"; `scale:false` keeps "20"), scientific expanded
+ * ("1.23E+05" → "123000"), accounting decorations stripped (parentheses negative, currency symbol
+ * / code and padding around the digits, U+2212 minus). A General (undefined) format accepts only a
+ * bare decimal with optional exponent (Excel never groups under General); `date` / `text` formats and
+ * anything that is not a recognisable rendering return the text UNCHANGED (total fail-soft).
+ * A rendering whose expansion leaves the finite-double domain (point shift beyond ±330, or a result
+ * overflowing ±e308) is not a recognisable rendering either — the text stays verbatim, so the output
+ * always satisfies parseNumber and a crafted clipboard cannot amplify itself in memory.
+ * Degenerate separators (empty decimal, or group equal to decimal) are a consumer error ⇒ RangeError.
+ * 表示済み数値から宣言区切りで素の正準 10 進文字列を復元: 桁区切り除去、percent は小数点シフトで ÷100
+ * (`scale:false` はそのまま)、scientific は展開、会計装飾 (括弧負数・通貨記号 / コード・詰め物・U+2212)
+ * を除去。General (undefined) は裸の 10 進 (+ 任意の指数) のみ、`date` / `text` と描画でない文字列は
+ * 無変更 (全域 fail-soft)。有限 double の外へ出る展開 (小数点シフト ±330 超、±e308 溢れ) も描画とは
+ * 認めず原文のまま — 出力は常に parseNumber に適合し、細工クリップボードのメモリ増幅も遮断。
+ * 退化した区切り (空の小数区切り・group = decimal) は消費者エラー ⇒ RangeError。
+ */
+export const numberDisplayToCanonical = (text: string, format: CellValueFormat | undefined, separators: NumberSeparators): string => {
+    if (separators.decimal === "" || separators.group === separators.decimal) {
+        throw new RangeError(`numberDisplayToCanonical: separators must declare a non-empty decimal separator distinct from the group separator (got group="${separators.group}", decimal="${separators.decimal}")`)
+    }
+    // 日付 / テキスト書式は数値描画ではない
+    if (format !== undefined && (format.type === "date" || format.type === "text")) {
+        return text
+    }
+    const kind = format === undefined ? "general" : format.type
+    let s = text.trim()
+    let negative = false
+    // 会計形式の括弧負数
+    if (s.startsWith("(") && s.endsWith(")")) {
+        negative = true
+        s = s.slice(1, -1).trim()
+    }
+    // percent は末尾 % が必須、他の型に % があれば描画ではない
+    if (kind === "percent") {
+        if (!s.endsWith("%")) {
+            return text
+        }
+        s = s.slice(0, -1).trim()
+    } else if (s.includes("%")) {
+        return text
+    }
+    // General は桁区切りを描画しない
+    const group = kind === "general" ? "" : separators.group
+    const exponentAllowed = kind === "scientific" || kind === "general"
+    const inCore = (c: string): boolean => (c >= "0" && c <= "9") || (group !== "" && group.includes(c)) || separators.decimal.includes(c) || (exponentAllowed && (c === "e" || c === "E"))
+    let start = 0
+    while (start < s.length && !inCore(s[start])) {
+        start += 1
+    }
+    let end = s.length
+    while (end > start && !inCore(s[end - 1])) {
+        end -= 1
+    }
+    // 前後の装飾: 負号は高々 1 つ (記号の内側の会計括弧 "$ (1,234.00)" も負)、通貨以外は空白しか許さない
+    let signs = 0
+    let opens = 0
+    let closes = 0
+    let decoration = ""
+    for (const c of s.slice(0, start)) {
+        if (MINUS_SIGNS.includes(c)) {
+            signs += 1
+        } else if (c === "(") {
+            opens += 1
+        } else {
+            decoration += c
+        }
+    }
+    for (const c of s.slice(end)) {
+        if (MINUS_SIGNS.includes(c)) {
+            signs += 1
+        } else if (c === ")") {
+            closes += 1
+        } else {
+            decoration += c
+        }
+    }
+    // 負の印 (負号 / 括弧対) は全体で高々 1 つ、括弧の不揃いは描画ではない
+    const marks = signs + opens
+    if (opens !== closes || marks > 1 || (marks === 1 && negative)) {
+        return text
+    }
+    negative = negative || marks === 1
+    if (kind !== "currency" && decoration.trim() !== "") {
+        return text
+    }
+    // 核の外側空白を落とす (空白系の桁区切りが記号の手前に残る形 "1 234 €" を救う)
+    const core = parseDisplayCore(s.slice(start, end).trim(), group, separators.decimal, kind === "scientific" ? "required" : kind === "general" ? "optional" : "none")
+    if (core === null) {
+        return text
+    }
+    // percent (scale 既定) は ÷100 = 小数点を 2 桁左へ
+    const percentShift = format !== undefined && format.type === "percent" && format.scale !== false ? -2 : 0
+    const shift = core.exponent + percentShift
+    // 値域フェンス: double の全域 (±e308) を越える小数点シフトは実在の Excel / Sheets 描画に無い。
+    // ADR-12 は行 × 列しか見ないため、展開すると ~7 文字の表示から最大 ~10,001 文字のセル文字列を
+    // 合成する敵対クリップボードがゲートを素通りする — 展開前に遮断する (描画と認めず原文のまま)
+    if (shift > 330 || shift < -330) {
+        return text
+    }
+    const canonical = canonicalDecimal(core.integer, core.fraction, shift, negative)
+    // フェンス内でも有限 double を溢れる展開 (例 "2E+308" → 2e308 = Infinity) は parseNumber が
+    // 拒む文字列になり selfCalc の不変量 (数値書式セルの正準文字列は数値文法に適合) を破る — 原文へ
+    return Number.isFinite(Number(canonical)) ? canonical : text
+}