minimal-agent 0.8.2 → 0.10.0

package/skills/ui-design/scripts/layout_balance.py

@@ -0,0 +1,881 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+layout_balance.py —— HTML→PPTX「构图均衡」确定性闸门（与 opc_check.py / layout_lint.py 互补）。
+
+为什么需要这个脚本？
+====================
+`export_pptx_from_html.mjs` 是**忠实搬运**：把 HTML 里每个元素的 getBoundingClientRect 线性映射到
+幻灯片坐标。所以 HTML 里「内容只占半张、挤在一角、文字框互相叠加」会被**逐像素照搬**进 PPT。
+这些缺陷此前**没有任何确定性检测器**：`check_ui_artifact.py` 只查分层标注，`opc_check.py` 只查
+OPC 合规，`pptx/layout_lint.py` 是为**原生 addShape 路径**调的（残桩连线 / shape 填充对比），在
+HTML 导出产物上几乎全部失效。于是「散文级构图铁律（黄金比例 / 禁止空半 / 禁止挤角）」只活在
+`references/layout-composition.md`，弱模型根本不遵守，构图全靠运气。
+
+本脚本读 `export_pptx_from_html.mjs` 写出的 `export-manifest.json`（其中 `slides[].balance` 已含
+确定性几何指标），把三类**可计算**的构图缺陷在产物上拦下，给弱模型一道**绕不过的防呆门槛**
+（与 layout_lint.py 同哲学，但作用在**对的产物**——HTML 几何，覆盖**对的缺陷**——均衡/空半/叠加）。
+
+检查项（任一 ERROR → 非零退出码 + 结构化问题：类型 · 位置 · 量化范围 + 可选修法提示）
+======================================================
+设计哲学（按用户原则）：闸门**只确定性地描述「哪种失衡 · 在哪页/哪半区 · 量化到多少」**，像 zod 报错——
+**不替 LLM 决定怎么改**。每条消息后缀的「｜可参考修法（非强制）」仅为提示，具体修法由调用方自定。
+★★ 当前策略（2026-06-19 起）：死守「重叠 / 截图夹带文本」，放宽「空」。
+   占空比族（B 页面过空 / 过半页面过空 / C·C' 空半挤角 / D 空心卡片）重新参与检测，
+   但默认作为 WARNING 反馈给生成循环，不作为硬门反复烧轮次；`content_boxes==0`「整页啥也没有」
+   仍是最小 sanity。重叠/裁切的「可参考修法」顺序为 **移动/重排 > 精炼文案 > 缩字（单次 ≤20%、仍 < 主标题）**。
+★ 死守「重叠」、放宽「空」：
+A. 内容相互叠加：非包含关系的文本/前景框显著相交（封面「标签/副标题压在大标题上」即此类）。**始终 ERROR。**
+   （同一前景块内的文本互叠——如 SVG 架构图密排标签——由导出器豁免，不计入。）
+B. 页面过空：内容覆盖率 < COVER_MIN。**单页仅 WARNING + 记账**；「过半有内容页都过空」也只做 WARNING。
+   整页啥也没有（content_boxes==0）：**有真实底图/视觉（hasBgImage/hasForegroundVisual）→ WARNING（纯图封面合法）；
+   否则 ERROR** —— 这条历来称「始终 ERROR」实为「无真实视觉才 ERROR」，坏页曾因 hasBgImage 误判(见 export
+   Gap A 修复)被误当纯图封面降级放行，故此处口径与代码严格对齐。
+C0. 内容严重飞出画布（catastrophic）：某元素可见部分 < OFFCANVAS_VISIBLE_MIN（如轨道被大图撑爆致内容跑到 x≈0.99）
+   = 观众根本看不到 → 计入 catastrophic 集合；`--strict-offcanvas` 时升 ERROR，`--catastrophic-only` 时是唯一硬门来源。
+C. 空半 / 挤角：某半区几乎无内容、对侧却满，或内容挤在一角。**有底图/前景视觉块 → WARNING**；无任何视觉才 ERROR。
+D. 空心卡片：**大**纯文本卡「卡内文字面积 ÷ 卡面积」< CARD_FILL_MIN（小卡/装饰件豁免）。有视觉/底图 → WARNING，
+   唯「大卡 + 无任何视觉」才 ERROR。媒体卡（hasMedia：含 img/svg/图标/大视觉块）本就不进检查。
+E. 文本裁切：文本内容显著超出自身框（导出会缩字/截断）。WARNING（提示，不拦；HTML 阶段就该让文字装得下）。
+
+「空」类（B/C/D）降级依据 = `hasBgImage`（真实大图铺满）**或** `hasForegroundVisual`（切出图的 img/svg/图标/
+大视觉块）——「有图不算空」。背景渐变/纯色不计入内容覆盖。**主门恒是「真重叠」（A，始终 ERROR）。**
+
+和 opc_check / layout_lint 一样：只用标准库（json / argparse / os / sys），忠实于最终产物，不替代视觉 QA。
+
+用法
+====
+    python layout_balance.py <export-manifest.json>        # 或传 workdir 目录，自动找 export-manifest.json
+    python layout_balance.py <dir> --verbose               # 额外打印每页指标明细
+"""
+
+import argparse
+import json
+import os
+import sys
+
+# 阈值（与 export_pptx_from_html.mjs 的 16×8 网格 + computeSlideBalance 配套）
+#
+# ★ 策略大改（2026-06-17）：实跑反复卡「空/不够满」→ 来回改 → 烧光 provider 5h 配额。用户裁决：
+#   **死守「重叠」，大幅放宽「空」**。重叠是真碰撞、一眼可见、改一次就好，必须硬拦；「空」是主观的、
+#   每页已要求 ≥1 视觉元素（AI图/SVG/图标），有图的页本就不算空，逼 AI 把每页填到高覆盖率只会
+#   无限烧轮次。于是「空」类全面降级：
+#   - **始终 ERROR（硬门）**：① 内容相互叠加（主门，报元素+重叠区+归一化坐标）
+#     ② 截图夹带 HTML/SVG 文本 ③ 整页啥也没有（content_boxes==0 且无视觉）。
+#   - **降级 WARNING（软门，提示不拦）**：单页过空、空半/挤角、空心卡片、文本裁切——尤其当本页
+#     **有底图或前景视觉块（图/SVG/图标）时**一律 WARNING（「有图不算空」）。
+#
+# COVER_MIN 0.26（标定史 0.42→0.55→0.45→0.40→0.26）：仅用于「单页是否记一笔过空账 + 是否参与
+#   『过半页空』统计」，单页低覆盖不再直接 FAIL。content_boxes==0 的真空页仍 ERROR（「就怕啥也没有」）。
+# CARD_FILL_MIN 0.28：纯文本卡填充率阈值（放宽自 0.35）；且仅 **大卡**（面积 ≥ CARD_MIN_AREA_FRAC）
+#   才量——小卡（引文 quote-pull / 装饰条 / 药丸）豁免（空心门本意是抓「大卡装一句话」，非装饰件）。
+#   命中也按 downgradeable 处理：有视觉/底图的页降 WARNING，唯「大卡 + 无任何视觉」才 ERROR。
+# 媒体卡（hasMedia：含 img/svg/图标/大视觉块）本就不进 cards——「卡内有图标不算空」已被导出器豁免。
+COVER_MIN = 0.26          # 单页内容覆盖率低于此 → 记一笔过空账（单页 WARNING；过半也只整体 WARNING）
+CARD_FILL_MIN = 0.28      # 大纯文本卡填充率低于此 → 空心卡（可降级：有视觉/底图→WARNING）
+CARD_MIN_AREA_FRAC = 0.06 # 卡面积（归一化 w×h）低于此 = 小卡（引文/装饰条/药丸），豁免空心检查
+EMPTY_PAGE_RATIO = 0.5    # 过空页占（有内容页）比例高于此 → 整体 WARNING（「不能页页空」）
+MIN_PAGES_FOR_EMPTY_RATIO = 3  # 有内容页 ≥ 此数才做「过半页空」整体判定（1~2 页稀疏可能是设计选择，只 WARNING）
+EMPTY_FRAC = 0.06         # 半区占用率低于此 → 视为「该半区几乎空白」
+OPP_MIN = 0.16            # 对侧半区占用率高于此，才把「这侧空」判为失衡（排除整页都空的退化情形）
+MAX_OVERLAP_REPORT = 6    # 单页最多列几条重叠，避免刷屏
+OFFCANVAS_VISIBLE_MIN = 0.20  # 越界元素「可见部分 ÷ 元素自身面积」低于此 = 内容实质飞出画布（catastrophic）。
+#   s9 事故：grid 轨道被大图撑爆，标题/正文全跑到 x≈0.99，可见 ~6% → 观众看不到。轻微越界(可见>20%)仍只 WARNING。
+
+# ★ --ppt-strict 专属阈值（2026-07-02 逐页体检裁决，见 ppt.yaml 阶段18）：默认模式一概不读，webppt 行为不变。
+#   重叠去噪：标题/副标题行盒贴边（0.01h 细带）与「膨胀行盒尾部盖住下方块」是 box 模型伪象，不是视觉碰撞——
+#   真机 deck 一页能刷出十几条，把真重叠（标题被卡压/药丸穿标题）淹没，修复 agent 追鬼。三条豁免规则见
+#   _ppt_strict_overlap_noise()。空卡升级：大面积纯空卡（slide05 白板/slide14 巨卡）从「有图可接受」升 ERROR，
+#   但被媒体块盖住 ≥PPT_STRICT_MEDIA_COVER 的卡是假空（图为兄弟绝对定位、DOM 不在卡内），豁免。
+PPT_STRICT_THIN_BAND = 0.02        # 重叠带宽/高低于此(归一化) + 占比小 = 行盒贴边噪声
+PPT_STRICT_THIN_FRAC = 0.30        # 贴边带同时要求 fracOfSmaller 低于此才豁免（大占比贴边仍是真碰撞）
+PPT_STRICT_CONTAIN_FRAC = 0.90     # 小框 ≥90% 被大框含住
+PPT_STRICT_CONTAIN_RATIO = 3.0     # 且大框面积 ≥3× 小框 → 父级膨胀行盒包含子元素，非碰撞
+PPT_STRICT_TAIL_FRAC = 0.35        # 重叠位于文本框底部 ≤35% 条带且高度 ≤35% 框高 → 行盒尾部伪象
+PPT_STRICT_CARD_AREA_MIN = 0.15    # 卡面积 ≥15% 页面才算「大空卡」候选
+PPT_STRICT_CARD_FILL_MAX = 0.10    # 填充 <10% 才升 ERROR（10%~28% 仍走默认 WARNING）
+PPT_STRICT_MEDIA_COVER = 0.70      # 单个媒体块盖住卡 ≥70% = 图卡假空，豁免
+PPT_STRICT_ESCAPE_TOL = 0.012      # 文字溢出卡片容差（占画布边长比例）：行盒舍入/降部噪声，低于此不报。
+PPT_STRICT_CAPTION_CONTAIN = 0.85  # 文字 ≥85% 落在媒体卡内 = caption/嵌套版式（fgParent 断链）→ 降 WARNING
+PPT_STRICT_MEDIA_TAGS = {"img", "svg", "picture", "video", "canvas"}  # 裸媒体元素自身作前景块（hasMedia 只查后代恒 false）
+PPT_STRICT_INFLATION_TOL = 0.008   # R6 原点匹配容差：重叠框与原始 textRun 的 (x,y) 距离（归一化）
+PPT_STRICT_RAW_OVERLAP_MIN = 0.05  # R6 用原始行盒重算后交叠占比低于此 = 导出加宽框幻影，剔除
+
+# ★ 信息集锦/综述型客户图（source_layout_plan.json 的 is_dense_info=true）渲染宽度下限：
+#   2026-07-07 真机 p8（20+ 圆形应用场景缩略图集锦）连续 3 次生成都没达到应有的视觉份量——
+#   ①小绝对定位框 ②满宽但 height:auto 撑爆画布 ③crash 修好但 flex 列共享缩水到 26% 宽——
+#   即便按 min_canvas_fraction（面积）算已达标（如 47%宽×26%高≈31%面积，压线通过通用 hero 下限
+#   0.30），object-fit:contain 在偏方/偏高宽高比的宽扁槽里仍会让密集图标挤压到实际可见宽度过窄、
+#   20+ 个并列信息点不可辨认——这是本身按面积算「合格」但按宽度看仍不达标的独立盲区，故用单独的
+#   宽度专属阈值（不是用它去改写/加严 min_canvas_fraction 的既有面积语义，避免误伤其它 display_role
+#   的合法窄高画幅证据图）。只在 source_layout_plan.json 存在且有 is_dense_info=true 条目时才激活，
+#   webppt 无此文件、此检查恒不触发。
+DENSE_INFO_MIN_WIDTH_FRACTION = 0.55
+#   注意：文字-父卡包含关系在导出器重叠检查里是**豁免项**（卡内文字属正常结构），所以「字顶出自家卡」
+#   此前完全不可见（slide13 CTA 恰因 fgParent 断链才漏网成一条重叠）。此检查读 measure-only 报告的
+#   顶层 textRuns（原始 HTML px 矩形，非 Office 加宽框）× balance.fgRects（全部前景块，含媒体卡），
+#   纯数据补上这个盲区；旧 report 缺字段时静默跳过。
+
+# ★ 占空比检测总开关（2026-06-18 停用 → 2026-06-19 用户裁决「加回但宽松」重新启用）：
+#   占空比族——页面过空(B) / 过半页面过空 / 空半·挤角(C/C') / 空心卡片(D)——重新参与检测，但**全程宽松**：
+#   - 单页缺陷一律走 `add(..., downgradeable=True)`：本页有底图/前景视觉块（图/SVG/图标）→ WARNING 不拦
+#     （配合「每页 ≥1 视觉元素」铁律，正常 deck 几乎都降 WARNING）；唯「真空白页 + 无任何视觉」才 ERROR。
+#   - 「过半页面过空」整体判定也降为 **WARNING**（不再整体 ERROR）。
+#   动因：用户要它**提示**「目录右半空」这类失衡（暴露给 build/export 循环去改），但**不硬拦**——守住「别再为
+#   『够不够满』反复改、烧光 provider 配额」的教训（真实事故）。重叠 / 截图夹带文本 / 字号 / 溢出各检测互不影响。
+#   置回 False 即一键全停（阈值常量 COVER_MIN/EMPTY_*/CARD_* 与代码全部保留、未删，仅被本开关守卫）。
+OCCUPANCY_CHECKS_ENABLED = True
+
+
+def _fmt_rect(r):
+    """把归一化 rect {x,y,w,h}（0–1，原点左上）格式化为可读坐标串；
+    缺字段（旧 manifest / 未富化的 measure 产物）时返回空串，调用方优雅降级。"""
+    if not isinstance(r, dict):
+        return ""
+    try:
+        return (
+            f"[x{float(r.get('x', 0)):.2f} y{float(r.get('y', 0)):.2f} "
+            f"w{float(r.get('w', 0)):.2f} h{float(r.get('h', 0)):.2f}]"
+        )
+    except (TypeError, ValueError):
+        return ""
+
+
+def _visible_fraction(rect) -> float:
+    """归一化 rect{x,y,w,h}（0–1，原点左上）与画布 [0,1]×[0,1] 相交面积 ÷ 元素自身面积。
+    = 元素「有多少落在可视区内」。1.0＝完全在内，接近 0＝几乎全飞出画布。
+    字段缺失/退化时返回 1.0（保守：宁可不误判为 catastrophic）。"""
+    if not isinstance(rect, dict):
+        return 1.0
+    try:
+        x = float(rect.get("x", 0.0))
+        y = float(rect.get("y", 0.0))
+        w = float(rect.get("w", 0.0))
+        h = float(rect.get("h", 0.0))
+    except (TypeError, ValueError):
+        return 1.0
+    if w <= 0 or h <= 0:
+        return 1.0
+    vis_w = max(0.0, min(x + w, 1.0) - max(x, 0.0))
+    vis_h = max(0.0, min(y + h, 1.0) - max(y, 0.0))
+    return (vis_w * vis_h) / (w * h)
+
+
+def _rect_area(r) -> float:
+    if not isinstance(r, dict):
+        return 0.0
+    try:
+        return max(0.0, float(r.get("w") or 0.0)) * max(0.0, float(r.get("h") or 0.0))
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _rect_intersect_area(a, b) -> float:
+    """两个归一化 rect 的相交面积；字段缺失返回 0。"""
+    if not isinstance(a, dict) or not isinstance(b, dict):
+        return 0.0
+    try:
+        ax, ay, aw, ah = (float(a.get(k) or 0.0) for k in ("x", "y", "w", "h"))
+        bx, by, bw, bh = (float(b.get(k) or 0.0) for k in ("x", "y", "w", "h"))
+    except (TypeError, ValueError):
+        return 0.0
+    iw = min(ax + aw, bx + bw) - max(ax, bx)
+    ih = min(ay + ah, by + bh) - max(ay, by)
+    return max(0.0, iw) * max(0.0, ih)
+
+
+def _ppt_strict_overlap_noise(ov) -> bool:
+    """--ppt-strict 的重叠去噪：True = 判为 box 模型伪象、剔除不报。
+
+    四条规则（2026-07-02 逐页体检标定，对照真机 deck 的 57 条重叠逐条验证）：
+    R1 行盒贴边：重叠带极细（min(w,h) < THIN_BAND）且占小框比例低 —— 标题/副标题 line-box 挨着。
+    R2 膨胀父盒包含：小框 ≥90% 被含住且大框 ≥3× —— 段落 rect 比字形区大得多，把下方 chip 圈进来。
+    R3 行盒尾部（纵向）：重叠只落在某文本框底部 ≤35% 条带内且高度 ≤35% 框高 —— 两行文字的 DOM 框
+       比实际字形高（h≈0.21 而字只占上 0.12），尾部空白盖住下方块。
+    R4 行盒尾部（横向）：重叠只落在某文本框右侧 ≤35% 条带内且宽度 ≤35% 框宽 —— 短文字撑满整列的
+       DOM 框（「一套系统」4 个字、框宽 0.34），右侧空白蹭到相邻卡。
+    真重叠（标题被卡压 22%/0.04h、buried 文本堆叠 88%）四条都豁免不掉，仍照报 ERROR。
+    """
+    r = ov.get("rect") or {}
+    try:
+        rw = float(r.get("w") or 0.0)
+        rh = float(r.get("h") or 0.0)
+        ry = float(r.get("y") or 0.0)
+        frac = float(ov.get("fracOfSmaller") or 0.0)
+    except (TypeError, ValueError):
+        return False
+    # R1 行盒贴边
+    if min(rw, rh) < PPT_STRICT_THIN_BAND and frac < PPT_STRICT_THIN_FRAC:
+        return True
+    a_rect = ov.get("aRect") or {}
+    b_rect = ov.get("bRect") or {}
+    area_a = _rect_area(a_rect)
+    area_b = _rect_area(b_rect)
+    big = max(area_a, area_b)
+    small = min(area_a, area_b)
+    # R2 膨胀父盒包含——仅 text⊃text（段落行盒比字形区大得多、把下方文字 chip 圈进来是伪象）。
+    # text⊃fg（文本框整个含住一张前景卡）**不豁免**：那是「字骑在卡上」（slide13 CTA 真缺陷，
+    # Office 加宽框恰好把面积比推过 3× 曾被此规则误杀）；fg 含 text 的正常结构已在导出器按
+    # fgParent 豁免，走到这里的 fg×text 包含都值得报。
+    if frac >= PPT_STRICT_CONTAIN_FRAC and small > 0 and big >= PPT_STRICT_CONTAIN_RATIO * small:
+        if ov.get("aKind") == "text" and ov.get("bKind") == "text":
+            return True
+    # R3/R4 行盒尾部（对文本框逐个试；纵向底部条带 / 横向右侧条带）
+    try:
+        rx = float(r.get("x") or 0.0)
+    except (TypeError, ValueError):
+        rx = 0.0
+    for rect, kind in ((a_rect, ov.get("aKind")), (b_rect, ov.get("bKind"))):
+        if kind != "text" or not isinstance(rect, dict):
+            continue
+        try:
+            th = float(rect.get("h") or 0.0)
+            ty = float(rect.get("y") or 0.0)
+            tw = float(rect.get("w") or 0.0)
+            tx = float(rect.get("x") or 0.0)
+        except (TypeError, ValueError):
+            continue
+        if th > 0 and rh <= PPT_STRICT_TAIL_FRAC * th and ry >= ty + (1.0 - PPT_STRICT_TAIL_FRAC) * th:
+            return True
+        if tw > 0 and rw <= PPT_STRICT_TAIL_FRAC * tw and rx >= tx + (1.0 - PPT_STRICT_TAIL_FRAC) * tw:
+            return True
+    return False
+
+
+def _run_rect_norm(run, canvas_w, canvas_h):
+    """textRun 的原始 HTML px 矩形 → 归一化 rect；字段坏/画布无效返回 None。"""
+    try:
+        rect = {
+            "x": float(run.get("x") or 0.0) / canvas_w,
+            "y": float(run.get("y") or 0.0) / canvas_h,
+            "w": float(run.get("w") or 0.0) / canvas_w,
+            "h": float(run.get("h") or 0.0) / canvas_h,
+        }
+    except (TypeError, ValueError, ZeroDivisionError):
+        return None
+    if rect["w"] <= 0 or rect["h"] <= 0:
+        return None
+    return rect
+
+
+def _match_raw_run(rect, raw_runs, canvas_w, canvas_h):
+    """按 (x,y) 原点把重叠框匹配回同 slide 的原始 textRun 行盒（导出加宽只改 w/h、不动原点）。
+    同一原点多个匹配取面积最小的（最接近真实字形区）；无匹配返回 None。"""
+    try:
+        rx = float(rect.get("x") or 0.0)
+        ry = float(rect.get("y") or 0.0)
+    except (TypeError, ValueError):
+        return None
+    best = None
+    for run in raw_runs:
+        rr = _run_rect_norm(run, canvas_w, canvas_h)
+        if not rr:
+            continue
+        if abs(rr["x"] - rx) <= PPT_STRICT_INFLATION_TOL and abs(rr["y"] - ry) <= PPT_STRICT_INFLATION_TOL:
+            if best is None or rr["w"] * rr["h"] < best["w"] * best["h"]:
+                best = rr
+    return best
+
+
+def _ppt_strict_frame_inflation(ov, raw_runs, canvas_w, canvas_h) -> bool:
+    """R6 导出加宽框幻影（2026-07-03 真机 09 页副标题案）：重叠几何用的是导出文本框
+    （自动换行/行距余量加宽后，h 可达真实行盒 2×）——副标题在 HTML 里与下方卡片根本不相交，
+    也会被报成【内容相互叠加】ERROR（09 页一页 3 条全是它）。用同 slide 的原始 textRuns
+    （HTML px 矩形）按原点匹配回真实行盒、重算交叠：几乎为零则判幻影剔除。
+    找不到匹配原始行盒 → 不动（旧报告缺 textRuns 时行为不变）。"""
+    sides = []
+    matched_any = False
+    for rect_key, kind_key in (("aRect", "aKind"), ("bRect", "bKind")):
+        rect = ov.get(rect_key)
+        if not isinstance(rect, dict):
+            return False
+        if ov.get(kind_key) == "text":
+            raw = _match_raw_run(rect, raw_runs, canvas_w, canvas_h)
+            if raw is not None:
+                # 原始行盒比导出框还大属异常，不采信（守恒：只用来收窄，不放大）。
+                if raw["w"] * raw["h"] < _rect_area(rect):
+                    rect = raw
+                    matched_any = True
+        sides.append(rect)
+    if not matched_any:
+        return False
+    inter = _rect_intersect_area(sides[0], sides[1])
+    small = min(_rect_area(sides[0]), _rect_area(sides[1]))
+    if small <= 0:
+        return False
+    return (inter / small) < PPT_STRICT_RAW_OVERLAP_MIN
+
+
+def _ppt_strict_media_caption(ov, media_fg_names) -> bool:
+    """R5 媒体卡内文字（2026-07-03 裁决）：文字基本整体（≥85%）落在**含媒体**前景卡内 =
+    caption/图内说明字类合法嵌套版式（fgParent 断链才漏成重叠）→ 几何门降 WARNING，
+    可读性交给像素门（text_readability_pixel 已覆盖卡内文字）。
+    不豁免：文字框反把卡含住（text⊃fg，slide13 CTA 真缺陷）、跨卡骑边（部分压边）、
+    非媒体卡包含（不透明白卡盖字是像素门盲区，宁可误报）。"""
+    a_kind, b_kind = ov.get("aKind"), ov.get("bKind")
+    if {a_kind, b_kind} != {"text", "fg"}:
+        return False
+    if a_kind == "text":
+        t_rect, f_rect, f_name = ov.get("aRect"), ov.get("bRect"), ov.get("b")
+    else:
+        t_rect, f_rect, f_name = ov.get("bRect"), ov.get("aRect"), ov.get("a")
+    if f_name not in media_fg_names:
+        return False
+    t_area = _rect_area(t_rect)
+    f_area = _rect_area(f_rect)
+    if t_area <= 0 or f_area <= 0 or t_area > f_area:
+        return False
+    return (_rect_intersect_area(t_rect, f_rect) / t_area) >= PPT_STRICT_CAPTION_CONTAIN
+
+
+def _stem(name):
+    return os.path.splitext(os.path.basename(str(name or "")))[0]
+
+
+def _load_dense_info_stems(source_layout_plan_path):
+    """读 source_layout_plan.json，只为 is_dense_info==true 的条目建 {stem: 原始 file 名} 映射，
+    候选 stem 同时含原图 file 与 enhanced_file（与 source_usage_check.py::_derived_candidates 同一套
+    约定——deck.html 引用的通常是 enhanced_ 派生图）。路径缺失/解析失败/无此类条目一律返回空 dict，
+    调用方据此静默跳过（该文件是 ppt 独有产物，webppt 不产出，天然不影响 webppt 行为）。"""
+    if not source_layout_plan_path or not os.path.isfile(source_layout_plan_path):
+        return {}
+    try:
+        with open(source_layout_plan_path, "r", encoding="utf-8") as f:
+            plan = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(plan, dict):
+        return {}
+    result = {}
+    for im in (plan.get("images") or []):
+        if not isinstance(im, dict) or not im.get("is_dense_info"):
+            continue
+        orig_file = im.get("file") or "?"
+        for name in (im.get("file"), im.get("enhanced_file")):
+            if isinstance(name, str) and name:
+                result[_stem(name)] = orig_file
+    return result
+
+
+def _resolve_manifest_path(path: str) -> str:
+    """传目录则补报告文件，传文件原样返回。
+
+    优先 layout-report.json（export --measure-only 的廉价 HTML 层量构图，不出 pptx），
+    其次 export-manifest.json（全量导出产物）。两者 schema 同源（mode + slides[].balance），
+    判定逻辑完全一致——构图闸门前置到 HTML 层后，循环读的就是 layout-report.json。
+    """
+    if os.path.isdir(path):
+        layout_report = os.path.join(path, "layout-report.json")
+        if os.path.isfile(layout_report):
+            return layout_report
+        return os.path.join(path, "export-manifest.json")
+    return path
+
+
+def check_balance(manifest_path: str, verbose: bool = False, occupancy_checks_enabled=None,
+                  strict_offcanvas: bool = False, catastrophic_only: bool = False,
+                  ppt_strict: bool = False, source_layout_plan_path: str = None):
+    """返回 (problems, warnings, detail_lines)。problems 非空 = 有 ERROR 级构图缺陷。
+
+    strict_offcanvas：内容严重飞出画布（可见 < OFFCANVAS_VISIBLE_MIN）升为 ERROR（默认仅 WARNING，行为不变）。
+    catastrophic_only：只把「内容不可见灾难」（严重越界 + 无真实视觉的空页）作为 problems 返回，
+      抑制重叠/夹带/占空族等既有信号——供 visual_quality_gate 做「回归安全」的硬门（不误伤只是相邻/嵌套的
+      良性重叠计数，守住『别再为占空反复烧配额』红线）。默认 False，逐字节保持既有行为。
+    ppt_strict：ppt 工作流视觉门专用严格档（2026-07-02 逐页体检裁决）——①重叠去噪（剔行盒贴边/膨胀父盒/
+      行盒尾部三类伪象，真重叠照报）②严重越界升 ERROR（含 strict_offcanvas）③大面积纯空卡升 ERROR
+      （被媒体块盖住 ≥70% 的图卡豁免，需 manifest 带 mediaRects）。默认 False，webppt 等默认调用行为不变。
+    source_layout_plan_path：可选，传入 ppt 工作流的 source_layout_plan.json 路径时，额外对
+      is_dense_info==true 的客户图按 mediaRects.sourceFile 反查其真实渲染宽度，低于
+      DENSE_INFO_MIN_WIDTH_FRACTION 报 WARNING（2026-07-07 p8 连续 3 次未达标后新增，只读不硬拦）。
+      默认 None：不做此检查，webppt 等既有调用行为不变。"""
+    if occupancy_checks_enabled is None:
+        occupancy_checks_enabled = OCCUPANCY_CHECKS_ENABLED
+    if ppt_strict:
+        strict_offcanvas = True  # 严格档天然含「严重越界升 ERROR」
+    if catastrophic_only:
+        strict_offcanvas = True  # 灾难集合天然含严重越界
+    problems = []
+    warnings = []
+    details = []
+    catastrophic = []  # 「内容不可见」灾难（严重越界 + 无真实视觉空页）；catastrophic_only 时作为唯一 problems 返回
+    dense_info_stems = _load_dense_info_stems(source_layout_plan_path)
+
+    if not os.path.isfile(manifest_path):
+        return ([f"找不到 manifest：{manifest_path}（先跑 export_pptx_from_html.mjs 产出 export-manifest.json）"], [], [])
+
+    try:
+        with open(manifest_path, "r", encoding="utf-8") as f:
+            manifest = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        return ([f"manifest 解析失败：{exc}"], [], [])
+
+    mode = manifest.get("mode")
+    slides = manifest.get("slides") or []
+    try:
+        canvas_w = float(manifest.get("width") or 1920)
+        canvas_h = float(manifest.get("height") or 1080)
+    except (TypeError, ValueError):
+        canvas_w, canvas_h = 1920.0, 1080.0
+    if mode != "hybrid":
+        # flat 整页一张图，无前景/文本几何可量——不闸门（但说清楚，避免「以为查过了」）。
+        return ([], [f"导出模式为 {mode!r}，非 hybrid：构图均衡闸门不适用（flat 是整页一张图）。"], [])
+
+    # 跨页统计「过空」：单页过空只记账（WARNING）；过半有内容页都过空也只整体 WARNING（不硬拦）。
+    empty_pages = []          # 覆盖率 < COVER_MIN 的页 label
+    content_page_count = 0    # 有内容页（content_boxes>0）总数，作过空占比的分母
+
+    for slide in slides:
+        idx = slide.get("index")
+        label = slide.get("label") or f"slide {idx}"
+        b = slide.get("balance")
+        if not b:
+            warnings.append(f"{label}：缺 balance 指标（跳过；可能是旧 manifest 或非 hybrid 页）。")
+            continue
+
+        has_bg = bool(b.get("hasBgImage"))
+        has_fg_visual = bool(b.get("hasForegroundVisual"))  # 切出图的 img/svg/图标/大视觉块
+        has_visual = has_bg or has_fg_visual                 # 「有图不算空」的统一判据
+        coverage = b.get("coverage") or 0.0
+        ho = b.get("halfOccupancy") or {}
+        overlaps = b.get("overlaps") or []
+        content_boxes = b.get("contentBoxes") or 0
+        cards = b.get("cards") or []                 # 卡片/底板填充率（文本+子块面积÷卡面积；填充不足软门）
+        overflow_runs = b.get("overflowRuns") or []  # 显著裁切的文本（溢出软门）
+        small_text = b.get("smallText") or []        # 字号低于放映级下限的文本段（字号软门）
+        baked_text = b.get("bakedText") or []        # 背景态仍可见的 HTML/伪元素文本（截图夹带，硬门）
+        off_canvas = b.get("offCanvas") or []        # 越出画布的文本/前景块（超画布软门）
+        low_contrast = b.get("lowContrast") or []    # 文字/背景对比度不足（深底深字等；一律 WARNING，不硬拦）
+
+        def add(msg, downgradeable):
+            """无任何视觉 → ERROR；有底图/前景视觉块（图/SVG/图标）→ 放宽为 WARNING（「有图不算空」）。"""
+            if has_visual and downgradeable:
+                warnings.append(msg + "（本页有底图/前景视觉元素，按可接受处理）")
+            else:
+                problems.append(msg)
+
+        if verbose:
+            empties = [k for k in ("top", "bottom", "left", "right") if (ho.get(k) or 0.0) < EMPTY_FRAC]
+            hollow = [c for c in cards if (c.get("fill") or 0.0) < CARD_FILL_MIN]
+            details.append(
+                f"{label}: 覆盖 {coverage*100:.0f}% | 半区 上{(ho.get('top') or 0)*100:.0f}"
+                f"/下{(ho.get('bottom') or 0)*100:.0f}/左{(ho.get('left') or 0)*100:.0f}/右{(ho.get('right') or 0)*100:.0f}"
+                f"{' | 空半['+'/'.join(empties)+']' if empties else ''}"
+                f"{' | 重叠'+str(len(overlaps)) if overlaps else ''}"
+                f"{' | 卡'+str(len(cards))+'(空心'+str(len(hollow))+')' if cards else ''}"
+                f"{' | 裁切'+str(len(overflow_runs)) if overflow_runs else ''}"
+                f" | 底图{'有' if has_bg else '无'} 前景图{'有' if has_fg_visual else '无'} | 块{content_boxes}"
+            )
+
+        # ── A. 内容相互叠加（始终 ERROR，封面撞车的克星） ──
+        # 消息格式：【问题类型】页 · 位置/对象 · 量化范围  ｜可参考修法（非强制）：…
+        # ppt_strict：先剔除行盒伪象（贴边/膨胀父盒/行盒尾部），只报真碰撞——修复 agent 不追鬼。
+        if ppt_strict:
+            overlaps = [ov for ov in overlaps if not _ppt_strict_overlap_noise(ov)]
+            # R6 导出加宽框幻影：用原始 textRuns 行盒重算，交叠归零的整条剔除（09 页副标题案）。
+            raw_runs = slide.get("textRuns") or []
+            if raw_runs:
+                overlaps = [
+                    ov for ov in overlaps
+                    if not _ppt_strict_frame_inflation(ov, raw_runs, canvas_w, canvas_h)
+                ]
+            # R5 媒体卡内文字：caption/图内说明字类合法嵌套（fgParent 断链）→ 降 WARNING 可见化，
+            # 不再吃修复轮预算；可读性由像素门裁决。旧 report 缺 fgRects → 集合为空、行为不变。
+            media_fg_names = {
+                fr.get("name")
+                for fr in (b.get("fgRects") or [])
+                if isinstance(fr, dict) and fr.get("name")
+                and (fr.get("hasMedia") or str(fr.get("tag") or "").lower() in PPT_STRICT_MEDIA_TAGS)
+            }
+            if media_fg_names:
+                caption_ids = {
+                    id(ov) for ov in overlaps if _ppt_strict_media_caption(ov, media_fg_names)
+                }
+                if caption_ids:
+                    for ov in overlaps:
+                        if id(ov) not in caption_ids:
+                            continue
+                        t_name = ov.get("a") if ov.get("aKind") == "text" else ov.get("b")
+                        f_name = ov.get("b") if ov.get("aKind") == "text" else ov.get("a")
+                        warnings.append(
+                            f"【媒体卡内文字】{label} · 「{t_name}」基本整体落在媒体卡「{f_name}」内"
+                            f"（caption/嵌套版式，fgParent 断链）——几何门不判错，可读性由像素门裁决；"
+                            f"若确属压图看不清请给文字加紧贴 scrim 或恢复 DOM 嵌套"
+                        )
+                    overlaps = [ov for ov in overlaps if id(ov) not in caption_ids]
+        for ov in overlaps[:MAX_OVERLAP_REPORT]:
+            a_rect = _fmt_rect(ov.get("aRect"))
+            b_rect = _fmt_rect(ov.get("bRect"))
+            o_rect = _fmt_rect(ov.get("rect"))
+            # 富报：哪两个元素@归一化坐标 × 重叠区@归一化坐标（坐标 = 元素左上/宽高 ÷ 画布宽高，0–1）。
+            # 字段缺失（旧 manifest）时降级为元素名对。
+            if o_rect:
+                where = (
+                    f" · 「{ov.get('a')}」{a_rect} ×「{ov.get('b')}」{b_rect}"
+                    f" · 重叠区{o_rect}（归一化 0–1，原点左上）"
+                )
+            else:
+                where = f" · 「{ov.get('a')}」×「{ov.get('b')}」"
+            # ppt_strict：文字与前景卡高包含重叠、且导出器没按 fgParent 豁免掉 = 多半是 wrapper
+            # 断链的「字骑出自家卡」（slide13 CTA 案）——补一条针对性的修法方向。
+            escape_hint = ""
+            if (
+                ppt_strict
+                and {ov.get("aKind"), ov.get("bKind")} == {"text", "fg"}
+                and (ov.get("fracOfSmaller") or 0.0) >= 0.8
+            ):
+                escape_hint = "；若该文字本属此卡片：加大卡片或让文字换行收纳"
+            problems.append(
+                f"【内容相互叠加】{label}{where} · "
+                f"重叠 {ov.get('areaIn')} in²（约占较小框 {ov.get('fracOfSmaller', 0)*100:.0f}%）"
+                f"  ｜可参考修法（非强制）：先移动/重排躲开（拉开间距·换槽位·调 grid 模板）"
+                f" → 再精炼/精简文案使其更短 → 最后缩小字体（最多缩 20%，且仍 < 该页主标题）"
+                f"{escape_hint}"
+            )
+        if len(overlaps) > MAX_OVERLAP_REPORT:
+            problems.append(
+                f"【内容相互叠加】{label} · 另有 {len(overlaps) - MAX_OVERLAP_REPORT} 处重叠未列出。"
+            )
+
+        # ── 文字溢出所属卡片（仅 ppt_strict；ERROR）──
+        # 「卡内文字」在重叠检查里是豁免项（正常结构），故字顶出自家卡此前完全不可见。
+        # 数据源：顶层 slide.textRuns（原始 HTML px 矩形）× balance.fgRects（全部前景块，含媒体卡）；
+        # 旧 report / 全量 manifest 缺任一字段 → 静默跳过（向后兼容）。
+        if ppt_strict:
+            fg_by_name = {}
+            for fr in (b.get("fgRects") or []):
+                if isinstance(fr, dict) and fr.get("name") and isinstance(fr.get("rect"), dict):
+                    fg_by_name[fr["name"]] = fr["rect"]
+            escapes = []
+            for run in (slide.get("textRuns") or []) if fg_by_name else []:
+                if not isinstance(run, dict):
+                    continue
+                parent = run.get("fgParent")
+                card = fg_by_name.get(parent)
+                if not parent or not isinstance(card, dict):
+                    continue
+                try:
+                    rx = float(run.get("x") or 0.0) / canvas_w
+                    ry = float(run.get("y") or 0.0) / canvas_h
+                    rw = float(run.get("w") or 0.0) / canvas_w
+                    rh = float(run.get("h") or 0.0) / canvas_h
+                    cx = float(card.get("x") or 0.0)
+                    cy = float(card.get("y") or 0.0)
+                    cw = float(card.get("w") or 0.0)
+                    ch = float(card.get("h") or 0.0)
+                except (TypeError, ValueError):
+                    continue
+                if rw <= 0 or rh <= 0 or cw <= 0 or ch <= 0:
+                    continue
+                sides = []
+                for zh, overhang, px_scale in (
+                    ("左缘", cx - rx, canvas_w),
+                    ("右缘", (rx + rw) - (cx + cw), canvas_w),
+                    ("上缘", cy - ry, canvas_h),
+                    ("下缘", (ry + rh) - (cy + ch), canvas_h),
+                ):
+                    if overhang > PPT_STRICT_ESCAPE_TOL:
+                        sides.append(f"{zh} {overhang * px_scale:.0f}px")
+                if sides:
+                    escapes.append((run, parent, sides, {"x": rx, "y": ry, "w": rw, "h": rh}))
+            for run, parent, sides, rrect in escapes[:MAX_OVERLAP_REPORT]:
+                problems.append(
+                    f"【文字溢出卡片】{label} · 「{(run.get('text') or 'text')[:16]}」{_fmt_rect(rrect)}"
+                    f" 超出所属卡片「{parent}」{_fmt_rect(fg_by_name.get(parent))}：{'、'.join(sides)}"
+                    f"  ｜可参考修法（非强制）：加大卡片（padding/尺寸随内容自然撑开）/ 让文字换行收进卡内 / 精炼文案——别缩字"
+                )
+            if len(escapes) > MAX_OVERLAP_REPORT:
+                problems.append(
+                    f"【文字溢出卡片】{label} · 另有 {len(escapes) - MAX_OVERLAP_REPORT} 处溢出未列出。"
+                )
+
+        # ── 截图夹带文本（始终 ERROR，与重叠同级硬门——用户硬要求：底图/中层切图绝不能带 HTML/SVG 文本） ──
+        # 探针 full 态查「未被 auto-text 覆盖的可见文本」：source=dom（漏标的真实文本，含前景块内→会烧进**中层切图**）
+        # / source=pseudo（::before/::after 文字）。会被烧进截图、不可编辑，且若上层又还原一层 → 双层。**唯一例外 AI 插图自带字。**
+        for bt in baked_text[:MAX_OVERLAP_REPORT]:
+            src = bt.get("source")
+            how = (
+                "改成真实 DOM 文本节点（h*/p/span），别放进 ::before/::after content"
+                if src == "pseudo"
+                else "确认该文字是真实可见文本节点（导出器会自动隐藏并提成可编辑框）；若刻意烧进图请标 data-pptx-export=\"ignore\""
+            )
+            problems.append(
+                f"【截图夹带文本】{label} · 「{bt.get('text')}」{_fmt_rect(bt.get('rect'))}"
+                f" · 未被隐藏、会烧进截图（{'伪元素 ' + src if src == 'pseudo' else 'DOM 漏标'}）"
+                f"  ｜可参考修法（非强制）：{how}"
+            )
+        if len(baked_text) > MAX_OVERLAP_REPORT:
+            problems.append(
+                f"【截图夹带文本】{label} · 另有 {len(baked_text) - MAX_OVERLAP_REPORT} 处未列出。"
+            )
+
+        # ── 文字/背景对比度不足（治「深紫底 + 黑字」不可读）：**一律 WARNING、不硬拦**。──
+        # 为什么不做 ERROR：硬门会逼导出步去改 deck.html 颜色，弱模型(doubao)改 HTML 极易出错/编码损坏 → 整步放弃 halt
+        # （真实事故，与当年占空门停用同因）。对比度治本在**上游设计铁律**（深底白字/浅底深字，见 layout-composition §0.9 +
+        # build/design prompt）；这里只确定性**报问题**给导出步顺手改（深底转白字，用 Edit），改不动也照常导出、不阻塞。
+        for lc in low_contrast[:MAX_OVERLAP_REPORT]:
+            ratio = lc.get("ratio") or 0.0
+            warnings.append(
+                f"【文字对比度不足】{label} · 「{lc.get('text')}」{_fmt_rect(lc.get('rect'))}"
+                f" · 文字 {lc.get('color')} / 背景 {lc.get('bgColor')} 对比度仅 {ratio}（放映级需 ≥3.0、正常 ≥4.5）"
+                f"  ｜可参考修法（非强制）：深底配浅/白字、浅底配深墨字——绝不深底深字或浅底浅字（VI 深色仅用于封面/章节且文字转白）"
+            )
+        if len(low_contrast) > MAX_OVERLAP_REPORT:
+            warnings.append(
+                f"【文字对比度不足】{label} · 另有 {len(low_contrast) - MAX_OVERLAP_REPORT} 处未列出。"
+            )
+
+        # ── 卡片/分组填充不足（D，占空族）：禁用时整体停用（迭代空列表即跳过）。──
+        # fill = 卡内（文本 + 子块）面积 ÷ 卡面积 → 同抓「大白卡装一句话」与「图元挤一角、旁边大片留白」（crammed group）。
+        # ppt_strict 附加语义（需 manifest 带 mediaRects，旧 manifest 缺字段时不升级、只走默认 WARNING）：
+        #   - 被单个媒体块盖住 ≥70% 的卡 = 图卡假空（图为兄弟绝对定位、DOM 不在卡内）→ 整条豁免；
+        #   - 大面积（≥15% 页）且填充 <10% 的真空板（slide05 白板/slide14 巨卡事故）→ 升 ERROR 不再「有图可接受」。
+        media_rects = b.get("mediaRects") or []
+        has_media_info = isinstance(b.get("mediaRects"), list)
+
+        # ── 信息集锦/综述型客户图槽位偏窄（仅 source_layout_plan_path 传入且有 is_dense_info 条目时激活）：
+        # WARNING 不硬拦——先观察几轮再考虑要不要升级，避免重蹈已回退的 canvas_fraction_violations
+        # 覆辙（那次是测错了维度；这次测的是 mediaRects 真实渲染框宽度，只是阈值本身仍需真机验证）。
+        if dense_info_stems:
+            for m in media_rects:
+                src = m.get("sourceFile") if isinstance(m, dict) else None
+                if not src:
+                    continue
+                orig_file = dense_info_stems.get(_stem(src))
+                if not orig_file:
+                    continue
+                actual_w = m.get("w") or 0.0
+                if actual_w < DENSE_INFO_MIN_WIDTH_FRACTION:
+                    warnings.append(
+                        f"【信息集锦图槽位偏窄】{label} · {orig_file} · "
+                        f"渲染宽度实测仅画布 {actual_w*100:.0f}%，此类图建议 ≥ {DENSE_INFO_MIN_WIDTH_FRACTION*100:.0f}%"
+                        f"（is_dense_info 客户图，20+ 并列信息点需要足够宽度才可辨认）"
+                        f"  ｜可参考修法（非强制）：给它独立整页，或与另一张图对半平分页面（各占约 50% 宽度）——"
+                        f"不要用共享列/共享行的纵向堆叠把它挤成次要辅助证据"
+                    )
+
+        for c in (cards if occupancy_checks_enabled else []):
+            fill = c.get("fill") or 0.0
+            rect = c.get("rect") or {}
+            area_frac = (rect.get("w") or 0.0) * (rect.get("h") or 0.0)
+            if area_frac < CARD_MIN_AREA_FRAC:
+                continue  # 小卡（引文 quote-pull / 装饰条 / 药丸）豁免：本意只抓「大卡/大底板填充不足」
+            if fill >= CARD_FILL_MIN:
+                continue
+            if ppt_strict and has_media_info and area_frac > 0:
+                media_cover = max(
+                    (_rect_intersect_area(rect, m) / area_frac for m in media_rects),
+                    default=0.0,
+                )
+                if media_cover >= PPT_STRICT_MEDIA_COVER:
+                    continue  # 图卡假空：媒体块盖着，不是真空板
+                if area_frac >= PPT_STRICT_CARD_AREA_MIN and fill < PPT_STRICT_CARD_FILL_MAX:
+                    problems.append(
+                        f"【空心大卡】{label} · 卡片/底板 {_fmt_rect(c.get('rect'))} · "
+                        f"占页面 {area_frac*100:.0f}% 而卡内内容仅 {fill*100:.0f}%（真空板）"
+                        f"  ｜可参考修法（非强制）：按内容收紧/删掉该卡 / 放大内部图元铺满 / 补实质内容"
+                    )
+                    continue
+            add(
+                f"【卡片/分组填充不足】{label} · 卡片/底板 {_fmt_rect(c.get('rect'))} · "
+                f"卡内内容（文字+子块）仅占 {fill*100:.0f}% < 阈值 {CARD_FILL_MIN*100:.0f}%（归一化 0–1，原点左上）"
+                f"  ｜可参考修法（非强制）：减小卡的 padding / 放大内部图元铺满 / 补 2–3 行实质文字或辅助元素"
+                f" / 按内容收紧卡尺寸（放大字号是末选，别只靠它把空卡撑满）",
+                downgradeable=True,
+            )
+
+        # ── 文本显著裁切 / 溢出（E，「挤压」语义，始终保留）：WARNING，导出会触发缩字或截断；HTML 阶段就该让文字装得下 ──
+        for o in overflow_runs:
+            warnings.append(
+                f"【文本裁切】{label} · 「{o.get('text')}」{_fmt_rect(o.get('rect'))}"
+                f" · 内容超出框 {o.get('overflowPx')}px"
+                f"  ｜可参考修法（非强制）：先加大框高/挪位给文字空间 → 再精炼/缩短文案 → 最后缩小字体（最多缩 20%），使其在框内不溢出"
+            )
+
+        # ── 字号过小（放映级，WARNING 不拦）：低于放映级下限的文本（投影上偏小）。治本在设计/生成阶段按 §0.85 阶梯放大 ──
+        for s in small_text[:MAX_OVERLAP_REPORT]:
+            warnings.append(
+                f"【字号过小】{label} · 「{s.get('text')}」{_fmt_rect(s.get('rect'))}"
+                f" · 实际 {s.get('fontSize')}px，低于放映级下限"
+                f"  ｜可参考修法（非强制）：按 layout-composition.md §0.85 放映级阶梯放大（正文 ~38px、注释 ~30px、图内文字同标准且图形画大装下）"
+            )
+        if len(small_text) > MAX_OVERLAP_REPORT:
+            warnings.append(
+                f"【字号过小】{label} · 另有 {len(small_text) - MAX_OVERLAP_REPORT} 处偏小文本未列出。"
+            )
+
+        # ── 超出画布（WARNING 不拦，与占空开关无关）：文本/前景块右/下越界（内容比 1920×1080 大、会被裁出可视区）。──
+        # 修法顺序 = 用户裁决：① 精炼文案 + 图文并茂（能用图表/SVG/图标表达的就别堆文字）→ ② 改两列 → ③ 拆成两页。
+        # 「内容多就换两页、别死磕一页」「字不能再小」——所以**绝不靠缩字**，靠精炼/图形化/拆页。
+        for oc in off_canvas[:MAX_OVERLAP_REPORT]:
+            base = (
+                f"【超出画布】{label} · {'文本' if oc.get('kind') == 'text' else '前景块'}「{oc.get('name')}」"
+                f"{_fmt_rect(oc.get('rect'))} 越出页面边界（内容塞太多）"
+            )
+            vis = _visible_fraction(oc.get("rect"))
+            if vis < OFFCANVAS_VISIBLE_MIN:
+                # 内容实质飞出画布、观众根本看不到（s9：轨道被大图撑爆，元素跑到 x≈0.99，可见 ~6%）。
+                msg = (
+                    base + f" · 可见部分仅 {vis*100:.0f}%（< {OFFCANVAS_VISIBLE_MIN*100:.0f}%，内容实质不可见）"
+                    f"  ｜可参考修法（非强制）：多为 grid/flex 轨道被大图/长内容撑爆 → 给分栏子项加 min-width:0；"
+                    f"或 ① 精炼文案图文并茂 → ② 改两列 → ③ 拆两页。**绝不缩字到 <24px**"
+                )
+                catastrophic.append(msg)
+                (problems if strict_offcanvas else warnings).append(msg)
+            else:
+                # ppt_strict：越界（>8px 容差后仍出界）一律 ERROR——「内容超出 PPT 下边缘」是用户点名缺陷
+                # （slide09 L4 卡 42% 被裁仍非 catastrophic，默认档只 WARNING 无人修）。默认档行为不变。
+                (problems if ppt_strict else warnings).append(
+                    base
+                    + "  ｜可参考修法（非强制）：① 精炼文案 + 图文并茂（图表/SVG/图标省字）→ ② 改两列 → ③ 拆成两页（别死磕一页）。**绝不缩字到 <24px**"
+                )
+        if len(off_canvas) > MAX_OVERLAP_REPORT:
+            warnings.append(
+                f"【超出画布】{label} · 另有 {len(off_canvas) - MAX_OVERLAP_REPORT} 处越界未列出。"
+            )
+
+        # 整页几乎无内容（连标题都没量到）——有**真实**底图/视觉则 WARNING（纯图封面合法），否则 ERROR（「就怕啥也没有」）。
+        # has_visual 的准确性依赖 export 侧 hasBgImage 不误判（Gap A 修复：撑爆/越界的大图不再算"背景"）。
+        if content_boxes == 0:
+            msg = (
+                f"【未量到内容】{label} · 全页无文本/前景框"
+                f"  ｜可参考检查（非强制）：是否标了 data-pptx-kind=\"text\" / data-pptx-layer=\"foreground\""
+            )
+            if has_visual:
+                warnings.append(msg + "（本页有底图/前景视觉元素，按可接受处理）")
+            else:
+                # 无任何真实视觉的空页 = 内容不可见灾难，恒 ERROR + 计入 catastrophic。
+                problems.append(msg)
+                catastrophic.append(msg)
+            continue
+
+        content_page_count += 1
+
+        # ── B. 页面过空（占空族）：禁用时停用（不记账、不 WARNING）。──
+        if occupancy_checks_enabled and coverage < COVER_MIN:
+            empty_pages.append(label)
+            warnings.append(
+                f"【页面过空】{label} · 内容覆盖 {coverage*100:.0f}% < 阈值 {COVER_MIN*100:.0f}%"
+                f"{'（有底图/视觉元素，可接受）' if has_visual else '（单页记一笔；过半页空才整体失败）'}"
+                f"  ｜可参考修法（非强制）：先从 draft.md 补更多实质要点 / 加辅助解释的 HTML 元素"
+                f"（图示·图标·要点卡·SVG·分隔带）/ 调分栏让两侧互补（放大字号·拉大卡片不是办法）"
+            )
+
+        # ── C. 空半（占空族）：一侧空、对侧满 = 失衡；禁用时停用。──
+        for empty_side, full_side, zh in (
+            ("top", "bottom", "上空下满"),
+            ("bottom", "top", "下空上满"),
+            ("left", "right", "左空右满"),
+            ("right", "left", "右空左满"),
+        ):
+            if (occupancy_checks_enabled
+                    and (ho.get(empty_side) or 0.0) < EMPTY_FRAC
+                    and (ho.get(full_side) or 0.0) > OPP_MIN):
+                add(
+                    f"【构图失衡·{zh}】{label} · {empty_side} 半区占用 {(ho.get(empty_side) or 0)*100:.0f}%"
+                    f" / {full_side} 半区 {(ho.get(full_side) or 0)*100:.0f}%"
+                    f"  ｜可参考修法（非强制）：空侧补实质要点或辅助解释 HTML 图形（图标/图示/要点卡）/ 调分栏让两侧互补填满",
+                    downgradeable=True,
+                )
+
+        # ── C'. 挤角（占空族）：横竖各有一侧空 → 内容堆在一角；禁用时停用。──
+        empties = {k for k in ("top", "bottom", "left", "right") if (ho.get(k) or 0.0) < EMPTY_FRAC}
+        if occupancy_checks_enabled and empties & {"top", "bottom"} and empties & {"left", "right"}:
+            corner = ("下" if "top" in empties else "上") + ("右" if "left" in empties else "左")
+            add(
+                f"【内容挤角·{corner}角】{label} · 空半区 [{'/'.join(sorted(empties))}]"
+                f"  ｜可参考修法（非强制）：把焦点移到黄金分割/三分线附近 / 空区补实质内容或辅助解释 HTML 元素，图文互补填满版面",
+                downgradeable=True,
+            )
+
+    # ── 「不能页页空」：单页过空只记账，过半有内容页都过空 = 整体失衡。**降为 WARNING（不硬拦）**——
+    #    占空族「加回但宽松」裁决：只提示别人去填，不阻断导出（避免为「够不够满」反复改烧配额）。
+    #    仅对 ≥ MIN_PAGES_FOR_EMPTY_RATIO 页的 deck 生效（1~2 页稀疏可能是设计选择，不误伤）。
+    if (
+        occupancy_checks_enabled
+        and content_page_count >= MIN_PAGES_FOR_EMPTY_RATIO
+        and len(empty_pages) > EMPTY_PAGE_RATIO * content_page_count
+    ):
+        listed = "、".join(empty_pages[:8]) + (" …" if len(empty_pages) > 8 else "")
+        warnings.append(
+            f"【过半页面过空】{len(empty_pages)}/{content_page_count} 个有内容页覆盖率 < {COVER_MIN*100:.0f}%"
+            f"（页页空、整体偏空）：{listed}"
+            f"  ｜可参考修法（非强制）：给空页补实质要点 + 辅助解释 HTML 元素（图标/图示/要点卡/SVG/图表），"
+            f"整体提升内容密度（不是放大字号/拉大卡片）"
+        )
+
+    # catastrophic_only：只交回「内容不可见灾难」，抑制重叠/夹带/占空族噪声（回归安全的硬门来源）。
+    if catastrophic_only:
+        return (catastrophic, warnings, details)
+    return (problems, warnings, details)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="HTML→PPTX 构图均衡 确定性闸门（读 export-manifest.json；与 opc_check / layout_lint 互补，仅标准库）"
+    )
+    parser.add_argument(
+        "manifest",
+        help="layout-report.json / export-manifest.json 路径，或其所在 workdir 目录"
+        "（目录时优先 layout-report.json）",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="打印每页指标明细")
+    parser.add_argument("--no-occupancy", action="store_true", help="关闭占空比族 warning（页面过空/空半/挤角/卡片填充不足）")
+    parser.add_argument("--strict-offcanvas", action="store_true",
+                        help="内容严重飞出画布（可见 < %d%%）升为 ERROR（默认仅 WARNING）" % int(OFFCANVAS_VISIBLE_MIN * 100))
+    parser.add_argument("--catastrophic-only", action="store_true",
+                        help="只把「内容不可见灾难」（严重越界 + 无真实视觉空页）作为 ERROR，抑制重叠/占空族噪声"
+                             "（供 visual_quality_gate 做回归安全的硬门）")
+    parser.add_argument("--ppt-strict", action="store_true",
+                        help="ppt 视觉门严格档：重叠去噪（剔行盒伪象）+ 严重越界升 ERROR + 大空卡升 ERROR"
+                             "（默认关；webppt 等既有调用行为不变）")
+    parser.add_argument("--source-layout-plan", default=None,
+                        help="ppt 工作流 source_layout_plan.json 路径（可选）：传入时额外检查"
+                             "is_dense_info 客户图的真实渲染宽度是否达标（WARNING，不硬拦）；"
+                             "webppt 无此文件，不传则跳过，行为不变")
+    args = parser.parse_args()
+
+    manifest_path = _resolve_manifest_path(args.manifest)
+    problems, warnings, details = check_balance(
+        manifest_path,
+        verbose=args.verbose,
+        occupancy_checks_enabled=(OCCUPANCY_CHECKS_ENABLED and not args.no_occupancy),
+        strict_offcanvas=args.strict_offcanvas,
+        catastrophic_only=args.catastrophic_only,
+        ppt_strict=args.ppt_strict,
+        source_layout_plan_path=args.source_layout_plan,
+    )
+
+    if args.verbose and details:
+        print("每页构图指标：")
+        for d in details:
+            print("  " + d)
+
+    if warnings:
+        for w in warnings:
+            print("WARNING: " + w)
+
+    if problems:
+        print(
+            f"构图均衡检查 FAILED —— {manifest_path} 存在 {len(problems)} 处缺陷"
+            f"（每条 = 【问题类型】页 · 位置 · 量化范围）："
+        )
+        for p in problems:
+            print("  - " + p)
+        print(
+            "说明：本闸门只确定性地**报问题与位置/范围**（像 zod 报错），「｜可参考修法」仅为提示、不强制——"
+            "具体怎么改由你决定。构图铁律见 ui-design/references/layout-composition.md。"
+            "**ERROR（必清零）：内容相互叠加（重叠）+ 截图夹带文本（底图/切图绝不能带 HTML/SVG 文字）+ 整页啥也没有。**"
+            "**WARNING（提示不拦）：文本溢出 + 字号过小（放映级）+ 超出画布 + 文字对比度不足（深底深字等）+ 占空比族（页面过空/空半/挤角/卡片·分组填充不足，已加回但宽松、有视觉即降级）。**"
+            "修法方向：**修「重叠/溢出」先移动/重排躲开 → 再精炼描述文案使其更短 → 最后才缩小字体（单次最多 20%，仍 < 主标题）；**"
+            "**「截图夹带文本」把该文字改成真实 DOM 文本节点（别放 ::before/::after / 别烧进图）。**"
+            "图被挤压时**绝不变形**：等比缩放 + object-position 按内容热区裁切平移、按槽位选对 aspect。"
+            "（本闸门不替代视觉 QA。）"
+        )
+        return 1
+
+    print(f"构图均衡检查 PASSED —— {manifest_path} 无可计算的构图缺陷（视觉 QA 仍需进行）。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())