@aiquants/spreadsheet 0.8.0

package/src/model/cellPaint.ts

@@ -0,0 +1,537 @@
+/**
+ * @fileoverview Effective cell format → cell paint (inline style + state attributes) and the
+ * editing sink's paint, interned per format object (v0.8 rich cells). Pure and React-free: the
+ * grid spreads `paint.style` / `paint.attrs` into the cell props and the editor applies
+ * `EditPaint.style` to the sink. Style keys are React / CSSOM camelCase property names so both
+ * consumers can spread or `Object.assign` them without a translation pass. Engine contract
+ * (each clause is mutation-gated — spec 07 §5.9):
+ * - TOTAL fail-soft: an unparseable colour, an unknown border style, a non-positive / non-finite
+ *   font size, a blank font family or an out-of-vocabulary alignment is SKIPPED WHOLE (never
+ *   substituted) while the rest of the format still paints; a format that paints nothing yields
+ *   null — the v0.1 identity path (no attribute, no style).
+ * - Border OWNERSHIP folding: a cell draws its own right / bottom sides and FOLDS its right
+ *   neighbour's left side and its below neighbour's top side onto them (own side wins on
+ *   conflict); its own left / top sides are drawn only when the cell sits on the grid's left /
+ *   top edge (`leftEdge` / `topEdge` — no visible neighbour to fold into; the caller passes the
+ *   next VISIBLE neighbour's base format, so hidden tracks never own a line). Every grid line is
+ *   therefore painted by exactly one cell and neighbours never double a border. Borders are
+ *   painted as inline `borderRight` / `borderBottom` (/ `borderLeft` / `borderTop`) shorthands
+ *   that override `.aqsp-cell`'s grid-line border in place — the cell box is border-box, so
+ *   widths up to 3 px never shift layout.
+ * - INTERNING: an interior cell whose neighbours fold nothing is a pure function of its format
+ *   object, so its paint (or its null) is interned in a WeakMap keyed by that object — the same
+ *   format object always yields the same paint identity (per-slice memos and React props stay
+ *   stable). Formats are treated as immutable values; paints are frozen.
+ * - Colour normalisation: hex 3 / 4 / 6 / 8, rgb() / rgba() (legacy comma and modern space
+ *   syntax, integer or percentage channels, number or percentage alpha), the 148 CSS named
+ *   colours and `transparent` → lowercase "#rrggbb" ("#rrggbbaa" only when the alpha is not
+ *   opaque); anything else → null.
+ * - Font size is declared in pt and painted as CSS px (pt × 4 / 3); the sink's line box is the
+ *   rounded px so the overlay can centre the caret line exactly like the cell's flex centring.
+ *
+ * 実効セル書式 → セル塗り (インラインスタイル + 状態属性) と編集シンクの塗り、書式 object 毎に
+ * intern (v0.8 リッチセル)。純関数・React 非依存: グリッドは `paint.style` / `paint.attrs` をセル
+ * props へ展開し、エディタは `EditPaint.style` をシンクへ適用。style のキーは React / CSSOM の
+ * camelCase プロパティ名 — 両消費者が変換なしに展開 / `Object.assign` できる。エンジン契約 (全条項
+ * を変異検証で封印 — spec 07 §5.9): 全経路 fail-soft (解釈不能な色 / 未知の罫線種 / 非正・非有限
+ * フォントサイズ / 空白のフォント族 / 語彙外の揃えは**丸ごとスキップ**し代替しない — 残りは塗る。
+ * 何も塗らない書式は null = v0.1 恒等経路)、罫線所有の畳込み (自セルは right / bottom を描き、
+ * 右隣の left と下隣の top を自分の right / bottom へ畳む — 競合は自セル優先。自分の left / top は
+ * グリッドの左端 / 上端 (`leftEdge` / `topEdge`) に居るときだけ描き、呼び手は次の**可視**隣接の
+ * base 書式を渡すので非表示トラックが線を持つことはない。各グリッド線を塗るセルは常に 1 つ。罫線
+ * はインラインの `borderRight` / `borderBottom` (/ `borderLeft` / `borderTop`) 短縮形で
+ * `.aqsp-cell` のグリッド線をその場で上書き — セル箱は border-box なので 3 px までの幅でレイアウト
+ * は動かない)、intern (隣接からの畳込みが無い内部セルは書式 object の純関数なので塗り (null も)
+ * を WeakMap で intern — 同 object は常に同 paint identity。書式は不変値として扱い、塗りは凍結)、
+ * 色正規化 (hex 3 / 4 / 6 / 8・rgb() / rgba() のカンマ / 空白構文・整数 / 百分率チャネル・148 の
+ * CSS 色名 + transparent → 小文字 "#rrggbb"、非不透明のときだけ "#rrggbbaa"、他は null)、
+ * フォントサイズは pt 宣言 → CSS px (pt × 4 / 3)、シンクの行箱は丸めた px。
+ */
+
+import { alignToJustify, BORDER_DEFAULT_COLOR, type CellAlign, type CellBorder, type CellBorderStyle, type CellFormat, type CellVerticalAlign } from "./cellFormat.ts"
+
+/**
+ * The paint of one cell: inline style (React / CSSOM camelCase keys) and `data-aqsp-*` state
+ * attributes, both frozen. Spread into the cell props by the grid.
+ * セル 1 つの塗り: インラインスタイル (React / CSSOM の camelCase キー) と `data-aqsp-*` 状態属性、
+ * どちらも凍結。グリッドがセル props へ展開する。
+ */
+export type CellPaint = { readonly style: Readonly<Record<string, string>>; readonly attrs: Readonly<Record<string, string>> }
+
+/**
+ * The editing sink's paint: inline style, the line box height in px the overlay centres
+ * (`round(pt × 4 / 3)`, DEFAULT_LINE_BOX_PX when the format sets no valid size) and the vertical
+ * alignment the overlay honours when placing that line box (`middle` = the cell's flex centring).
+ * 編集シンクの塗り: インラインスタイル、オーバーレイが中央に置く行箱の高さ px (`round(pt × 4 / 3)`、
+ * 有効なサイズ指定が無ければ DEFAULT_LINE_BOX_PX)、その行箱を置くときにオーバーレイが従う垂直揃え
+ * (`middle` = セルの flex 中央)。
+ */
+export type EditPaint = { readonly style: Readonly<Record<string, string>>; readonly lineBoxPx: number; readonly verticalAlign: CellVerticalAlign }
+
+/** Line box of the default 13 px cell font — the sink's line box when no valid font size is set. / 既定 13 px セルフォントの行箱 — 有効なフォントサイズ指定が無いときのシンクの行箱。 */
+export const DEFAULT_LINE_BOX_PX = 13
+
+/** The sink's paint while idle and for any format that paints nothing (returned BY IDENTITY so callers can skip the write). / 待機中および何も塗らない書式のシンク塗り (identity で返すため呼び手は書込を省ける)。 */
+export const IDLE_EDIT_PAINT: EditPaint = Object.freeze({ style: Object.freeze({}), lineBoxPx: DEFAULT_LINE_BOX_PX, verticalAlign: "middle" })
+
+/**
+ * The 148 CSS named colours (CSS Color Level 4 — includes the gray / grey pairs and
+ * rebeccapurple) plus `transparent`, keyed by lowercase name. A closed vocabulary: anything not
+ * listed is not a colour (null), never guessed.
+ * CSS 色名 148 種 (CSS Color Level 4 — gray / grey の対と rebeccapurple を含む) + `transparent`、
+ * 小文字名をキーとする。閉じた語彙: 未掲載は色でない (null)、推測しない。
+ */
+const NAMED_COLOR_TABLE = {
+    aliceblue: "#f0f8ff",
+    antiquewhite: "#faebd7",
+    aqua: "#00ffff",
+    aquamarine: "#7fffd4",
+    azure: "#f0ffff",
+    beige: "#f5f5dc",
+    bisque: "#ffe4c4",
+    black: "#000000",
+    blanchedalmond: "#ffebcd",
+    blue: "#0000ff",
+    blueviolet: "#8a2be2",
+    brown: "#a52a2a",
+    burlywood: "#deb887",
+    cadetblue: "#5f9ea0",
+    chartreuse: "#7fff00",
+    chocolate: "#d2691e",
+    coral: "#ff7f50",
+    cornflowerblue: "#6495ed",
+    cornsilk: "#fff8dc",
+    crimson: "#dc143c",
+    cyan: "#00ffff",
+    darkblue: "#00008b",
+    darkcyan: "#008b8b",
+    darkgoldenrod: "#b8860b",
+    darkgray: "#a9a9a9",
+    darkgreen: "#006400",
+    darkgrey: "#a9a9a9",
+    darkkhaki: "#bdb76b",
+    darkmagenta: "#8b008b",
+    darkolivegreen: "#556b2f",
+    darkorange: "#ff8c00",
+    darkorchid: "#9932cc",
+    darkred: "#8b0000",
+    darksalmon: "#e9967a",
+    darkseagreen: "#8fbc8f",
+    darkslateblue: "#483d8b",
+    darkslategray: "#2f4f4f",
+    darkslategrey: "#2f4f4f",
+    darkturquoise: "#00ced1",
+    darkviolet: "#9400d3",
+    deeppink: "#ff1493",
+    deepskyblue: "#00bfff",
+    dimgray: "#696969",
+    dimgrey: "#696969",
+    dodgerblue: "#1e90ff",
+    firebrick: "#b22222",
+    floralwhite: "#fffaf0",
+    forestgreen: "#228b22",
+    fuchsia: "#ff00ff",
+    gainsboro: "#dcdcdc",
+    ghostwhite: "#f8f8ff",
+    gold: "#ffd700",
+    goldenrod: "#daa520",
+    gray: "#808080",
+    green: "#008000",
+    greenyellow: "#adff2f",
+    grey: "#808080",
+    honeydew: "#f0fff0",
+    hotpink: "#ff69b4",
+    indianred: "#cd5c5c",
+    indigo: "#4b0082",
+    ivory: "#fffff0",
+    khaki: "#f0e68c",
+    lavender: "#e6e6fa",
+    lavenderblush: "#fff0f5",
+    lawngreen: "#7cfc00",
+    lemonchiffon: "#fffacd",
+    lightblue: "#add8e6",
+    lightcoral: "#f08080",
+    lightcyan: "#e0ffff",
+    lightgoldenrodyellow: "#fafad2",
+    lightgray: "#d3d3d3",
+    lightgreen: "#90ee90",
+    lightgrey: "#d3d3d3",
+    lightpink: "#ffb6c1",
+    lightsalmon: "#ffa07a",
+    lightseagreen: "#20b2aa",
+    lightskyblue: "#87cefa",
+    lightslategray: "#778899",
+    lightslategrey: "#778899",
+    lightsteelblue: "#b0c4de",
+    lightyellow: "#ffffe0",
+    lime: "#00ff00",
+    limegreen: "#32cd32",
+    linen: "#faf0e6",
+    magenta: "#ff00ff",
+    maroon: "#800000",
+    mediumaquamarine: "#66cdaa",
+    mediumblue: "#0000cd",
+    mediumorchid: "#ba55d3",
+    mediumpurple: "#9370db",
+    mediumseagreen: "#3cb371",
+    mediumslateblue: "#7b68ee",
+    mediumspringgreen: "#00fa9a",
+    mediumturquoise: "#48d1cc",
+    mediumvioletred: "#c71585",
+    midnightblue: "#191970",
+    mintcream: "#f5fffa",
+    mistyrose: "#ffe4e1",
+    moccasin: "#ffe4b5",
+    navajowhite: "#ffdead",
+    navy: "#000080",
+    oldlace: "#fdf5e6",
+    olive: "#808000",
+    olivedrab: "#6b8e23",
+    orange: "#ffa500",
+    orangered: "#ff4500",
+    orchid: "#da70d6",
+    palegoldenrod: "#eee8aa",
+    palegreen: "#98fb98",
+    paleturquoise: "#afeeee",
+    palevioletred: "#db7093",
+    papayawhip: "#ffefd5",
+    peachpuff: "#ffdab9",
+    peru: "#cd853f",
+    pink: "#ffc0cb",
+    plum: "#dda0dd",
+    powderblue: "#b0e0e6",
+    purple: "#800080",
+    rebeccapurple: "#663399",
+    red: "#ff0000",
+    rosybrown: "#bc8f8f",
+    royalblue: "#4169e1",
+    saddlebrown: "#8b4513",
+    salmon: "#fa8072",
+    sandybrown: "#f4a460",
+    seagreen: "#2e8b57",
+    seashell: "#fff5ee",
+    sienna: "#a0522d",
+    silver: "#c0c0c0",
+    skyblue: "#87ceeb",
+    slateblue: "#6a5acd",
+    slategray: "#708090",
+    slategrey: "#708090",
+    snow: "#fffafa",
+    springgreen: "#00ff7f",
+    steelblue: "#4682b4",
+    tan: "#d2b48c",
+    teal: "#008080",
+    thistle: "#d8bfd8",
+    tomato: "#ff6347",
+    turquoise: "#40e0d0",
+    violet: "#ee82ee",
+    wheat: "#f5deb3",
+    white: "#ffffff",
+    whitesmoke: "#f5f5f5",
+    yellow: "#ffff00",
+    yellowgreen: "#9acd32",
+    transparent: "#00000000",
+} as const
+
+/** Name → normalised hex lookup (a Map so prototype keys such as "constructor" can never resolve). / 色名 → 正規化 hex の索引 (Map なので "constructor" 等の prototype キーは決して解決しない)。 */
+const NAMED_COLORS: ReadonlyMap<string, string> = new Map(Object.entries(NAMED_COLOR_TABLE))
+
+/** Hex colour grammar: exactly 3 / 4 / 6 / 8 hex digits after "#" (5 and 7 never match). / hex 色文法: "#" の後に 3 / 4 / 6 / 8 桁ちょうど (5 桁・7 桁は不成立)。 */
+const HEX_COLOR = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/
+
+/** rgb() / rgba() envelope; the argument text is tokenised separately. / rgb() / rgba() の外形。引数文字列は別途トークン化。 */
+const RGB_FUNCTION = /^rgba?\((.*)\)$/
+
+/** Percentage token grammar shared by channels and alpha. / チャネルと alpha が共有する百分率トークン文法。 */
+const PERCENT_TOKEN = /^(\d+(?:\.\d+)?)%$/
+
+/** One byte → two lowercase hex digits. / 1 バイト → 小文字 hex 2 桁。 */
+const byteToHex = (value: number): string => value.toString(16).padStart(2, "0")
+
+/** One rgb() channel token: integer 0-255 or percentage 0-100 % (rounded to a byte); null outside the grammar or range. / rgb() チャネル 1 トークン: 整数 0-255 か百分率 0-100 % (バイトへ丸め)。文法 / 範囲外は null。 */
+const parseChannel = (token: string): number | null => {
+    const percent = PERCENT_TOKEN.exec(token)
+    if (percent !== null) {
+        const value = Number(percent[1])
+        return value <= 100 ? Math.round((value * 255) / 100) : null
+    }
+    // 整数のみ (CSS は小数チャネルも受けるが、正規化の語彙は整数バイトに閉じる)
+    if (!/^\d+$/.test(token)) {
+        return null
+    }
+    const value = Number(token)
+    return value <= 255 ? value : null
+}
+
+/** The alpha token: number 0-1 or percentage 0-100 % → byte (rounded); null outside the grammar or range. / alpha トークン: 数値 0-1 か百分率 0-100 % → バイト (丸め)。文法 / 範囲外は null。 */
+const parseAlpha = (token: string): number | null => {
+    const percent = PERCENT_TOKEN.exec(token)
+    if (percent !== null) {
+        const value = Number(percent[1])
+        return value <= 100 ? Math.round((value * 255) / 100) : null
+    }
+    if (!/^(?:\d+(?:\.\d+)?|\.\d+)$/.test(token)) {
+        return null
+    }
+    const value = Number(token)
+    return value <= 1 ? Math.round(value * 255) : null
+}
+
+/** Normalises the argument text of rgb() / rgba(): 3 channels + optional alpha, comma or whitespace (+ "/") separated. / rgb() / rgba() の引数文字列を正規化: 3 チャネル + 任意 alpha、カンマまたは空白 (+ "/") 区切り。 */
+const normalizeRgbArguments = (inner: string): string | null => {
+    // 旧構文 (カンマ) と新構文 (空白 + "/") を同じトークン列へ。空引数・末尾区切りは空トークンになり不正
+    const tokens = inner.trim().split(/\s*[,/]\s*|\s+/)
+    if (tokens.length !== 3 && tokens.length !== 4) {
+        return null
+    }
+    const red = parseChannel(tokens[0])
+    const green = parseChannel(tokens[1])
+    const blue = parseChannel(tokens[2])
+    if (red === null || green === null || blue === null) {
+        return null
+    }
+    const rgb = `#${byteToHex(red)}${byteToHex(green)}${byteToHex(blue)}`
+    if (tokens.length === 3) {
+        return rgb
+    }
+    const alpha = parseAlpha(tokens[3])
+    if (alpha === null) {
+        return null
+    }
+    // 不透明 alpha は 6 桁へ畳む (同じ色は同じ文字列 — intern キーとしての正準性)
+    return alpha === 255 ? rgb : `${rgb}${byteToHex(alpha)}`
+}
+
+/**
+ * CSS colour text → lowercase "#rrggbb" ("#rrggbbaa" when not opaque) or null when the text is
+ * not a colour this engine knows (hex 3 / 4 / 6 / 8, rgb() / rgba(), the CSS named colours,
+ * `transparent`). Whitespace-trimmed and case-insensitive. null means "ignore" — the caller
+ * skips the property whole; nothing is ever substituted.
+ * CSS 色文字列 → 小文字 "#rrggbb" (非不透明なら "#rrggbbaa")、このエンジンが知らない文字列は null
+ * (hex 3 / 4 / 6 / 8・rgb() / rgba()・CSS 色名・`transparent`)。前後空白は除き大小文字は無視。
+ * null は「無視」— 呼び手はプロパティを丸ごとスキップし、代替は決してしない。
+ */
+export const normalizeColor = (text: string): string | null => {
+    const t = text.trim().toLowerCase()
+    const hex = HEX_COLOR.exec(t)
+    if (hex !== null) {
+        const digits = hex[1]
+        // 3 / 4 桁は各 nibble を倍化 (#abc → #aabbcc)。8 桁の alpha "ff" は不透明 = 6 桁へ畳む
+        const expanded = digits.length <= 4 ? digits.replace(/./g, (nibble) => nibble + nibble) : digits
+        return expanded.length === 8 && expanded.endsWith("ff") ? `#${expanded.slice(0, 6)}` : `#${expanded}`
+    }
+    const fn = RGB_FUNCTION.exec(t)
+    if (fn !== null) {
+        return normalizeRgbArguments(fn[1])
+    }
+    const named = NAMED_COLORS.get(t)
+    return named === undefined ? null : named
+}
+
+/** Border style → CSS width (px) and line style (thin 1 / medium 2 / thick 3 solid, dashed 1, dotted 1, double 3, hair 1 dotted). / 罫線種 → CSS 幅 (px) と線種。 */
+const BORDER_LINE: Readonly<Record<CellBorderStyle, { readonly width: number; readonly line: string }>> = {
+    thin: { width: 1, line: "solid" },
+    medium: { width: 2, line: "solid" },
+    thick: { width: 3, line: "solid" },
+    dashed: { width: 1, line: "dashed" },
+    dotted: { width: 1, line: "dotted" },
+    double: { width: 3, line: "double" },
+    hair: { width: 1, line: "dotted" },
+}
+
+/**
+ * CSS border shorthand value ("1px solid #000000" etc.) for one border side, or null when the
+ * border is skipped whole: an unknown style, or a colour that does not normalise. An absent
+ * colour is the stated default BORDER_DEFAULT_COLOR (not a fallback for a bad one).
+ * 罫線 1 辺の CSS border 短縮値 ("1px solid #000000" 等)、丸ごとスキップなら null: 未知の線種、
+ * または正規化できない色。色の省略は宣言済み既定 BORDER_DEFAULT_COLOR (不正な色の代替ではない)。
+ */
+export const borderCss = (border: CellBorder): string | null => {
+    // 語彙外の線種は丸ごとスキップ — Object.hasOwn で prototype キー ("constructor") も弾く
+    if (!Object.hasOwn(BORDER_LINE, border.style)) {
+        return null
+    }
+    const line = BORDER_LINE[border.style]
+    // 色の省略は宣言済み既定、指定があれば正規化 — 解釈不能なら辺ごとスキップ (既定への置換はしない)
+    const color = border.color === undefined ? BORDER_DEFAULT_COLOR : normalizeColor(border.color)
+    return color === null ? null : `${line.width}px ${line.line} ${color}`
+}
+
+/** Vertical alignment → the flex cell's align-items. / 垂直揃え → flex セルの align-items。 */
+const VERTICAL_ALIGN_ITEMS: Readonly<Record<CellVerticalAlign, string>> = { top: "flex-start", middle: "center", bottom: "flex-end" }
+
+/** Closed-vocabulary guard for align (anything else is skipped whole). / align の閉じた語彙ガード (他は丸ごとスキップ)。 */
+const isCellAlign = (align: unknown): align is CellAlign => align === "left" || align === "center" || align === "right"
+
+/** Closed-vocabulary guard for verticalAlign. / verticalAlign の閉じた語彙ガード。 */
+const isVerticalAlign = (align: unknown): align is CellVerticalAlign => align === "top" || align === "middle" || align === "bottom"
+
+/** Font size in pt → CSS px (pt × 4 / 3) when finite and positive; null otherwise (skipped whole, never substituted). / pt → CSS px (pt × 4 / 3)、有限かつ正のときだけ。他は null (丸ごとスキップ・代替しない)。 */
+const fontPx = (pt: number | undefined): number | null => (typeof pt === "number" && Number.isFinite(pt) && pt > 0 ? (pt * 4) / 3 : null)
+
+/**
+ * Writes the text-level paint shared by the cell and the sink — colours (normalised), weight,
+ * style, decoration, family, size and wrap — into `style`, skipping every invalid value whole.
+ * セルとシンクが共有する文字水準の塗り — 色 (正規化済み)・太さ・斜体・装飾・フォント族・サイズ・
+ * 折返し — を `style` へ書く。無効な値は丸ごとスキップ。
+ */
+const writeTextPaint = (effective: CellFormat, style: Record<string, string>): void => {
+    // 色は正規化できたときだけ (解釈不能は丸ごとスキップ)
+    if (typeof effective.background === "string") {
+        const background = normalizeColor(effective.background)
+        if (background !== null) {
+            style.background = background
+        }
+    }
+    if (typeof effective.color === "string") {
+        const color = normalizeColor(effective.color)
+        if (color !== null) {
+            style.color = color
+        }
+    }
+    // 真偽値は厳密に true のみ (truthy な非真偽値は語彙外 = スキップ)
+    if (effective.bold === true) {
+        style.fontWeight = "bold"
+    }
+    if (effective.italic === true) {
+        style.fontStyle = "italic"
+    }
+    // 下線と取消線は 1 つの text-decoration へ合成
+    const underline = effective.underline === true
+    const strikethrough = effective.strikethrough === true
+    if (underline || strikethrough) {
+        style.textDecoration = underline && strikethrough ? "underline line-through" : underline ? "underline" : "line-through"
+    }
+    // 空白だけのフォント族は無指定と同じ (CSSOM が拒む値を書かない)
+    if (typeof effective.fontFamily === "string" && effective.fontFamily.trim() !== "") {
+        style.fontFamily = effective.fontFamily
+    }
+    const px = fontPx(effective.fontSize)
+    if (px !== null) {
+        style.fontSize = `${px}px`
+    }
+    if (effective.wrap === true) {
+        style.whiteSpace = "pre-wrap"
+    }
+}
+
+/** One side's CSS: the cell's own border when valid (own wins on conflict), else the neighbour's folded side, else null. / 1 辺の CSS: 自セルの辺が有効ならそれ (競合は自セル優先)、無ければ隣接から畳んだ辺、無ければ null。 */
+const resolveSide = (own: CellBorder | undefined, folded: CellBorder | undefined): string | null => {
+    const ownCss = own === undefined ? null : borderCss(own)
+    if (ownCss !== null) {
+        return ownCss
+    }
+    // 自セルの辺が無指定 / 無効なら隣接の辺を畳む
+    return folded === undefined ? null : borderCss(folded)
+}
+
+/** Builds a cell paint from scratch (no interning). / セル塗りを素から構築 (intern なし)。 */
+const buildCellPaint = (effective: CellFormat | undefined, foldRight: CellBorder | undefined, foldBottom: CellBorder | undefined, leftEdge: boolean, topEdge: boolean): CellPaint | null => {
+    const style: Record<string, string> = {}
+    const attrs: Record<string, string> = {}
+    if (effective !== undefined) {
+        // 明示 align だけ塗る — 未指定の自動揃え (値依存) は呼び手が resolveCellAlign で解決する
+        if (isCellAlign(effective.align)) {
+            attrs["data-aqsp-align"] = effective.align
+            style.justifyContent = alignToJustify(effective.align)
+        }
+        if (isVerticalAlign(effective.verticalAlign)) {
+            attrs["data-aqsp-valign"] = effective.verticalAlign
+            style.alignItems = VERTICAL_ALIGN_ITEMS[effective.verticalAlign]
+        }
+        if (effective.wrap === true) {
+            attrs["data-aqsp-wrap"] = ""
+        }
+        writeTextPaint(effective, style)
+    }
+    // 罫線所有: right / bottom は自セル優先で隣接の辺を畳む。left / top は端のセルだけが直接描く
+    const borders = effective?.borders
+    const right = resolveSide(borders?.right, foldRight)
+    if (right !== null) {
+        style.borderRight = right
+    }
+    const bottom = resolveSide(borders?.bottom, foldBottom)
+    if (bottom !== null) {
+        style.borderBottom = bottom
+    }
+    if (leftEdge) {
+        const left = resolveSide(borders?.left, undefined)
+        if (left !== null) {
+            style.borderLeft = left
+        }
+    }
+    if (topEdge) {
+        const top = resolveSide(borders?.top, undefined)
+        if (top !== null) {
+            style.borderTop = top
+        }
+    }
+    // 何も塗らなければ null (v0.1 恒等経路)
+    if (Object.keys(style).length === 0 && Object.keys(attrs).length === 0) {
+        return null
+    }
+    return Object.freeze({ style: Object.freeze(style), attrs: Object.freeze(attrs) })
+}
+
+/** Interned paints (or nulls) of interior cells, keyed by format object identity. / 内部セルの intern 済み塗り (null 含む)、書式 object の identity がキー。 */
+const paintCache = new WeakMap<CellFormat, CellPaint | null>()
+
+/**
+ * Computes the paint of one cell from its effective format and the BASE formats of its right and
+ * below neighbours (border folding — own right / bottom win), plus whether the cell sits on the
+ * grid's left / top edge (only then it draws its own left / top). Interned by `effective`
+ * identity in a WeakMap when the cell is interior and neither neighbour folds a border (the
+ * common case — the same format object always yields the same paint identity); computed per call
+ * otherwise. Returns null when nothing paints — the v0.1 identity path.
+ * 実効書式と右 / 下隣の base 書式 (罫線畳込み — 自セルの right / bottom 優先)、およびグリッドの
+ * 左端 / 上端に居るか (そのときだけ自分の left / top を描く) からセル塗りを計算。内部セルで両隣が
+ * 辺を畳まないとき (通常の場合 — 同 object は常に同 paint identity) は `effective` の identity で
+ * WeakMap に intern、それ以外は呼出毎に計算。何も塗らなければ null = v0.1 恒等経路。
+ */
+export const resolveCellPaint = (effective: CellFormat | undefined, rightBase: CellFormat | undefined, belowBase: CellFormat | undefined, leftEdge: boolean, topEdge: boolean): CellPaint | null => {
+    // 隣接から畳み込む辺: 右隣の left → 自分の right、下隣の top → 自分の bottom
+    const foldRight = rightBase?.borders?.left
+    const foldBottom = belowBase?.borders?.top
+    // 畳込みも端所有も無い内部セルは書式 object の純関数 — WeakMap intern の対象
+    const interior = !(leftEdge || topEdge) && foldRight === undefined && foldBottom === undefined
+    if (effective === undefined) {
+        return interior ? null : buildCellPaint(undefined, foldRight, foldBottom, leftEdge, topEdge)
+    }
+    if (!interior) {
+        return buildCellPaint(effective, foldRight, foldBottom, leftEdge, topEdge)
+    }
+    const cached = paintCache.get(effective)
+    if (cached !== undefined) {
+        return cached
+    }
+    const paint = buildCellPaint(effective, undefined, undefined, false, false)
+    paintCache.set(effective, paint)
+    return paint
+}
+
+/**
+ * The editing sink's paint for a cell format: the text-level style (colours, weight, style,
+ * decoration, family, size, wrap — alignment is NOT included, the editor's own text-align path
+ * owns it), the line box `round(pt × 4 / 3)` (DEFAULT_LINE_BOX_PX without a valid size) and the
+ * vertical alignment (`middle` when unset or out of vocabulary — the cell's flex centring).
+ * Returns IDLE_EDIT_PAINT by identity for undefined and for any format that changes nothing.
+ * セル書式に対する編集シンクの塗り: 文字水準の style (色・太さ・斜体・装飾・フォント族・サイズ・
+ * 折返し — 揃えは含めない、シンクの text-align はエディタ既存経路の所有)、行箱 `round(pt × 4 / 3)`
+ * (有効なサイズが無ければ DEFAULT_LINE_BOX_PX)、垂直揃え (未指定 / 語彙外は `middle` = セルの flex
+ * 中央)。undefined と何も変えない書式には IDLE_EDIT_PAINT を identity で返す。
+ */
+export const resolveEditPaint = (effective: CellFormat | undefined): EditPaint => {
+    if (effective === undefined) {
+        return IDLE_EDIT_PAINT
+    }
+    const style: Record<string, string> = {}
+    writeTextPaint(effective, style)
+    const px = fontPx(effective.fontSize)
+    const lineBoxPx = px === null ? DEFAULT_LINE_BOX_PX : Math.round(px)
+    const verticalAlign = isVerticalAlign(effective.verticalAlign) ? effective.verticalAlign : "middle"
+    // 書式があっても何も塗らず既定の行箱 / 中央揃えなら IDLE と identity 同一 (呼び手の「書込不要」判定に使える)
+    if (Object.keys(style).length === 0 && lineBoxPx === DEFAULT_LINE_BOX_PX && verticalAlign === "middle") {
+        return IDLE_EDIT_PAINT
+    }
+    return Object.freeze({ style: Object.freeze(style), lineBoxPx, verticalAlign })
+}