12.1 高明度低饱和调色板

{
  "themeId": "cozy-clean",
  "constraints": {
    "neutralRoles": ["bg", "surface", "ink", "muted"],
    "accentRoles": ["accent", "ok", "warn", "danger"],
    "lumaFloor": { "bg": 230, "surface": 200, "ink": 60, "muted": 90 },
    "satCapNeutralPermille": 300, "accentMax": 4
  }
}

#!/usr/bin/env python3
# file: sim/st12_palette.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/st12_palette.py
"""清新/治愈：高明度低饱和调色板的整数账（第 12 章 12.1，S 层）。

读 config/st12_palette.json（本章整数约束 + 候选色表）+ config/sp16_themes.json（取 cozy-clean
实例，也是《星屑旅店》默认主题）+ config/visual_spec.json（对比度下限）。三类整数检查：
**明度下限**（bg/surface/ink/muted 的 luma709 必须达各自下限）、**饱和度上限**（中性角色饱和度不超
satCapNeutralPermille）、**强调色数量**（accent 角色数不超 accentMax）。并依同一份 spec 用 PIL
真生成色卡 PNG。落 out/st12_palette.json 供 P 层对照。luma709 与饱和度都是整数类，逐位一致。
"""
import csv
import hashlib
import json
import os
import sys

from PIL import Image, ImageDraw

ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
GEN = os.path.join(ROOT, "out", "gen")
SRGB = (0.04045, 12.92, 0.055, 1.055, 2.4)
LUMA = (0.2126, 0.7152, 0.0722)


def srgb_to_linear(c: int) -> float:
    s = c / 255
    return s / SRGB[1] if s <= SRGB[0] else ((s + SRGB[2]) / SRGB[3]) ** SRGB[4]


def contrast10(a, b) -> int:
    f = lambda c: sum(LUMA[i] * srgb_to_linear(c[i]) for i in range(3))
    hi, lo = sorted((f(a), f(b)), reverse=True)
    return round(((hi + 0.05) / (lo + 0.05)) * 10)


def luma709(c) -> int:
    """整数明度（×10000 地板除），整数类，逐位一致。"""
    return (2126 * c[0] + 7152 * c[1] + 722 * c[2]) // 10000


def sat_permille(c) -> int:
    mx = max(c)
    return 0 if mx == 0 else (mx - min(c)) * 1000 // mx


def audit_proposal(p, cons):
    errs = []
    if p["role"] in cons["neutralRoles"]:
        if luma709(p["rgb"]) < cons["lumaFloor"][p["role"]]:
            errs.append("E_LUMA_FLOOR")
        if sat_permille(p["rgb"]) > cons["satCapNeutralPermille"]:
            errs.append("E_SAT_CAP")
    return errs


def gen_palette_card(tokens, path):
    cols, cell = list(tokens.values()), 24
    im = Image.new("RGB", (cell * len(cols), 48))
    d = ImageDraw.Draw(im)
    for i, c in enumerate(cols):
        d.rectangle([i * cell, 0, (i + 1) * cell - 1, 47], fill=tuple(c))
    im.save(path)


def main() -> int:
    cfg = json.load(open(os.path.join(ROOT, "config/st12_palette.json"), encoding="utf-8"))
    spec = json.load(open(os.path.join(ROOT, "config/visual_spec.json"), encoding="utf-8"))
    themes = json.load(open(os.path.join(ROOT, "config/sp16_themes.json"), encoding="utf-8"))
    th = next(t for t in themes["themes"] if t["id"] == cfg["themeId"])
    tokens, cons = th["tokens"], cfg["constraints"]
    min_c10 = min(contrast10(tokens[a], tokens[b]) for a, b in spec["contrastPairs"])
    accent_count = sum(1 for r in tokens if r in cons["accentRoles"])
    violations, rows = [], []
    for p in cfg["proposals"]:
        errs = audit_proposal(p, cons)
        violations += [{"id": p["id"], "code": c} for c in errs]
        rows.append({"id": p["id"], "role": p["role"], "luma": luma709(p["rgb"]),
                     "sat": sat_permille(p["rgb"]), "ok": not errs})
    if accent_count > cons["accentMax"]:
        violations.append({"id": "palette", "code": "E_ACCENT_COUNT"})
    neutrals = cons["neutralRoles"]
    neutral_sat = sum(sat_permille(tokens[r]) for r in neutrals) // len(neutrals)
    counts = {}
    for v in violations:
        counts[v["code"]] = counts.get(v["code"], 0) + 1
    canon = json.dumps({"tokenCount": len(tokens), "minContrast10": min_c10,
                        "proposalCount": len(cfg["proposals"]), "violationCount": len(violations),
                        "neutralSatMeanPermille": neutral_sat},
                       separators=(",", ":"), ensure_ascii=False)
    summary = {"project": cfg["project"], "themeId": cfg["themeId"], "tokenMatch": tokens == cfg["tokens"],
               "tokenCount": len(tokens), "minContrast10": min_c10, "contrastFloor10": spec["contrastFloor10"],
               "contrastPass": min_c10 >= spec["contrastFloor10"], "accentCount": accent_count,
               "accentMax": cons["accentMax"], "neutralSatMeanPermille": neutral_sat,
               "lumaFloor": cons["lumaFloor"], "satCapNeutralPermille": cons["satCapNeutralPermille"],
               "tokenLuma": {r: luma709(tokens[r]) for r in tokens},
               "tokenSat": {r: sat_permille(tokens[r]) for r in tokens},
               "proposalCount": len(cfg["proposals"]), "violationCount": len(violations),
               "counts": counts, "violations": violations, "rows": rows,
               "canonical": canon, "digest": hashlib.sha256(canon.encode("utf-8")).hexdigest()[:16]}
    os.makedirs(GEN, exist_ok=True)
    json.dump(summary, open(os.path.join(ROOT, "out/st12_palette.json"), "w", encoding="utf-8"),
              ensure_ascii=False, indent=2, sort_keys=True)
    with open(os.path.join(ROOT, "out/st12_palette.csv"), "w", encoding="utf-8", newline="") as f:
        wr = csv.writer(f)
        wr.writerow(["id", "role", "luma", "sat", "ok"])
        for r in rows:
            wr.writerow([r["id"], r["role"], r["luma"], r["sat"], str(r["ok"]).lower()])
    gen_palette_card(tokens, os.path.join(GEN, "st12_palette_card.png"))
    print(f"tokenCount={len(tokens)} minContrast10={min_c10} contrastPass={summary['contrastPass']}")
    print(f"bgLuma={luma709(tokens['bg'])} surfaceLuma={luma709(tokens['surface'])} "
          f"inkLuma={luma709(tokens['ink'])} mutedLuma={luma709(tokens['muted'])}")
    print(f"bgSat={sat_permille(tokens['bg'])} surfaceSat={sat_permille(tokens['surface'])} "
          f"neutralSatMeanPermille={neutral_sat}")
    print(f"accentCount={accent_count}/{cons['accentMax']} proposals={len(cfg['proposals'])} "
          f"violations={len(violations)} counts={counts}")
    for v in violations:
        print(f"  {v['id']:20s} {v['code']}")
    print(f"digest={summary['digest']}")
    print("wrote out/st12_palette.json out/st12_palette.csv out/gen/st12_palette_card.png")
    return 0


if __name__ == "__main__":
    sys.exit(main())

tokenCount=8 minContrast10=46 contrastPass=True
bgLuma=240 surfaceLuma=220 inkLuma=81 mutedLuma=99
bgSat=61 surfaceSat=96 neutralSatMeanPermille=168
accentCount=4/4 proposals=5 violations=4 counts={'E_LUMA_FLOOR': 2, 'E_SAT_CAP': 2}
  alt-bg-cool          E_LUMA_FLOOR
  alt-surface-tan      E_LUMA_FLOOR
  alt-surface-tan      E_SAT_CAP
  alt-muted-warm       E_SAT_CAP
digest=24653930f4f8368c
wrote out/st12_palette.json out/st12_palette.csv out/gen/st12_palette_card.png

// file: core/src/st12/palette.ts
// tier: P
// verify: node --test 'core/test/st12_*.test.ts'
// 高明度低饱和调色板的 TS 侧校验器（第 12 章 12.1）。与 sim/st12_palette.py 共用
// config/st12_palette.json、config/visual_spec.json、config/sp16_themes.json；判据全是字符串与
// 整数（明度 luma709、饱和度千分比、强调色数、对比度 ×10），故两侧违例集合与摘要逐位一致。
// 对比度复用 sp00/spec.ts 的同源常数。只允许可擦除 TS 语法（禁 enum / namespace / 参数属性 / 装饰器）。

import { contrast10 } from "../sp00/spec.ts";

export type RGB = number[];
export type Tokens = Record<string, RGB>;
export type Proposal = { id: string; role: string; rgb: RGB; note: string };
export type Constraints = { neutralRoles: string[]; accentRoles: string[];
  lumaFloor: Record<string, number>; satCapNeutralPermille: number; accentMax: number };
export type PaletteCfg = { themeId: string; tokens: Tokens; constraints: Constraints; proposals: Proposal[] };
export type Theme = { id: string; tokens: Tokens; strokePermille: number; detailPermille: number };
export type Spec = { contrastPairs: string[][]; contrastFloor10: number };
export type Violation = { id: string; code: string };
export type PaletteReport = { tokenMatch: boolean; tokenCount: number; minContrast10: number;
  contrastFloor10: number; contrastPass: boolean; accentCount: number; accentMax: number;
  neutralSatMeanPermille: number; proposalCount: number; violationCount: number;
  counts: Record<string, number>; violations: Violation[]; canonical: string; digest: string };

/** 整数明度 ×10000 地板除：整数类，逐位一致。 */
export function luma709(c: RGB): number {
  return Math.floor((2126 * c[0] + 7152 * c[1] + 722 * c[2]) / 10000);
}

/** 饱和度千分比：整数地板除，禁用浮点。 */
export function satPermille(c: RGB): number {
  const mx = Math.max(...c);
  return mx === 0 ? 0 : Math.floor(((mx - Math.min(...c)) * 1000) / mx);
}

export function tokensEqual(a: Tokens, b: Tokens): boolean {
  const ka = Object.keys(a);
  if (ka.length !== Object.keys(b).length) return false;
  return ka.every((k) => k in b && a[k].length === b[k].length && a[k].every((v, i) => v === b[k][i]));
}

export function auditProposal(p: Proposal, cons: Constraints): string[] {
  const errs: string[] = [];
  if (cons.neutralRoles.includes(p.role)) {
    if (luma709(p.rgb) < cons.lumaFloor[p.role]) errs.push("E_LUMA_FLOOR");
    if (satPermille(p.rgb) > cons.satCapNeutralPermille) errs.push("E_SAT_CAP");
  }
  return errs;
}

export function auditPalette(cfg: PaletteCfg, spec: Spec, themes: { themes: Theme[] }): PaletteReport {
  const th = themes.themes.find((t) => t.id === cfg.themeId);
  if (!th) throw new Error("themes 缺 " + cfg.themeId + " 实例");
  const tokens = th.tokens;
  const cons = cfg.constraints;
  const minContrast10 = Math.min(...spec.contrastPairs.map(([a, b]) => contrast10(tokens[a], tokens[b])));
  const accentCount = Object.keys(tokens).filter((k) => cons.accentRoles.includes(k)).length;
  const violations: Violation[] = [];
  for (const p of cfg.proposals) for (const c of auditProposal(p, cons)) violations.push({ id: p.id, code: c });
  if (accentCount > cons.accentMax) violations.push({ id: "palette", code: "E_ACCENT_COUNT" });
  const neutrals = cons.neutralRoles;
  const neutralSatMeanPermille = Math.floor(
    neutrals.reduce((s, r) => s + satPermille(tokens[r]), 0) / neutrals.length);
  const counts: Record<string, number> = {};
  for (const v of violations) counts[v.code] = (counts[v.code] ?? 0) + 1;
  const report: PaletteReport = {
    tokenMatch: tokensEqual(tokens, cfg.tokens), tokenCount: Object.keys(tokens).length, minContrast10,
    contrastFloor10: spec.contrastFloor10, contrastPass: minContrast10 >= spec.contrastFloor10,
    accentCount, accentMax: cons.accentMax, neutralSatMeanPermille, proposalCount: cfg.proposals.length,
    violationCount: violations.length, counts, violations, canonical: "", digest: "",
  };
  report.canonical = canonical(report);
  return report;
}

/** canonical 摘要：键序固定，与 Python 侧同序、无空白，供 sha256 对拍。 */
export function canonical(r: PaletteReport): string {
  return JSON.stringify({ tokenCount: r.tokenCount, minContrast10: r.minContrast10,
    proposalCount: r.proposalCount, violationCount: r.violationCount,
    neutralSatMeanPermille: r.neutralSatMeanPermille });
}

palette digest = 24653930f4f8368c
✔ 正例：token 与 cozy-clean 主题一致、对比度达下限、强调色不超上限 (0.477125ms)
✔ 跨语言：违例集合、计数与摘要逐位一致（整数类） (1.042042ms)
✔ 负例：明度不足、饱和度越界各自可被单独触发 (0.109125ms)
✔ 地板除锁死：明度与饱和度不得用浮点，token 相等判据逐通道比较 (0.091667ms)
ℹ tests 12
ℹ pass 12
ℹ fail 0