minimal-agent 0.8.2 → 0.10.0

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

@@ -0,0 +1,927 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+layout_balance_test.py —— layout_balance.py 的回归锚（stdlib unittest，仿 layout_lint_test 风格）。
+
+直接手搓最小 export-manifest.json（mode=hybrid + slides[].balance），分别命中
+重叠 / 过空 / 空半 / 挤角，并验证「有全幅底图(hasBgImage) 时 B/C 降级为 WARNING、但重叠永远 ERROR」
+以及「均衡页零问题」「flat 模式不闸门」。不依赖导出器实际跑，只测策略与阈值。
+
+运行：python skills/ui-design/scripts/layout_balance_test.py
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+from contextlib import contextmanager
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import layout_balance  # noqa: E402  （为切换 OCCUPANCY_CHECKS_ENABLED 开关）
+from layout_balance import _resolve_manifest_path, check_balance  # noqa: E402
+
+
+@contextmanager
+def occupancy_enabled():
+    """临时把占空比检测开关置 True（**现默认即 True**，2026-06-19「加回但宽松」裁决后此 cm 多为冗余明示）。
+    切换的是 layout_balance 模块自身的配置常量（非 mock.module），用完还原。"""
+    old = layout_balance.OCCUPANCY_CHECKS_ENABLED
+    layout_balance.OCCUPANCY_CHECKS_ENABLED = True
+    try:
+        yield
+    finally:
+        layout_balance.OCCUPANCY_CHECKS_ENABLED = old
+
+
+@contextmanager
+def occupancy_disabled():
+    """临时把占空比检测开关置 False（验证「一键全停」仍能关掉占空族，只留重叠/夹带文本/溢出/字号）。"""
+    old = layout_balance.OCCUPANCY_CHECKS_ENABLED
+    layout_balance.OCCUPANCY_CHECKS_ENABLED = False
+    try:
+        yield
+    finally:
+        layout_balance.OCCUPANCY_CHECKS_ENABLED = old
+
+
+def balance(coverage, top, bottom, left, right, overlaps=None, has_bg=False, boxes=8,
+            cards=None, overflow_runs=None, has_fg_visual=False, small_text=None, baked_text=None,
+            off_canvas=None, low_contrast=None):
+    return {
+        "grid": {"cols": 16, "rows": 8},
+        "contentBoxes": boxes,
+        "hasBgImage": has_bg,
+        "hasForegroundVisual": has_fg_visual,  # 切出图的 img/svg/图标/大视觉块（「有图不算空」降级依据）
+        "coverage": coverage,
+        "halfOccupancy": {"top": top, "bottom": bottom, "left": left, "right": right},
+        "bbox": {"x": 0, "y": 0, "w": 1920, "h": 1080},
+        "centroid": {"x": 960, "y": 540},
+        "overlaps": overlaps or [],
+        "cards": cards or [],              # 卡片/底板填充率（文本+子块面积÷卡面积；填充不足软门）
+        "overflowRuns": overflow_runs or [],  # 显著裁切的文本（溢出软门）
+        "smallText": small_text or [],     # 字号低于放映级下限的文本段（字号软门）
+        "bakedText": baked_text or [],     # 背景态仍可见的 HTML/伪元素文本（截图夹带，硬门）
+        "offCanvas": off_canvas or [],     # 越出画布的文本/前景块（超画布软门）
+        "lowContrast": low_contrast or [], # 文字/背景对比度不足（严重+纯底→硬门）
+    }
+
+
+def lc(ratio, bg_solid=True, text="文字", color="rgb(17,18,26)", bg="rgb(27,26,49)"):
+    return {"text": text, "ratio": ratio, "color": color, "bgColor": bg,
+            "bgSolid": bg_solid, "rect": {"x": 0.1, "y": 0.1, "w": 0.5, "h": 0.05}}
+
+
+def card(fill, x=0.05, y=0.15, w=0.44, h=0.40, fg_id="fg-0-0"):
+    return {"fgId": fg_id, "fill": fill, "rect": {"x": x, "y": y, "w": w, "h": h}}
+
+
+def write_manifest(slides, mode="hybrid"):
+    fd, path = tempfile.mkstemp(suffix=".json")
+    os.close(fd)
+    manifest = {"mode": mode, "width": 1920, "height": 1080, "slides": []}
+    for i, b in enumerate(slides, start=1):
+        manifest["slides"].append({"index": i, "label": f"{i:02d} 测试页", "balance": b})
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f)
+    return path
+
+
+OVERLAP = [{"a": "标题", "b": "副标题", "aKind": "text", "bKind": "text", "areaIn": 0.6, "fracOfSmaller": 0.4}]
+
+# 富化重叠（带归一化坐标 0–1）：computeSlideBalance 现给每个重叠加 aRect/bRect/rect。
+OVERLAP_COORDS = [{
+    "a": "大标题", "b": "副标题", "aKind": "text", "bKind": "text",
+    "areaIn": 0.6, "fracOfSmaller": 0.4,
+    "aRect": {"x": 0.05, "y": 0.70, "w": 0.50, "h": 0.12},
+    "bRect": {"x": 0.05, "y": 0.78, "w": 0.40, "h": 0.06},
+    "rect": {"x": 0.05, "y": 0.78, "w": 0.40, "h": 0.04},
+}]
+
+
+class LayoutBalanceTest(unittest.TestCase):
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _run(self, slides, mode="hybrid"):
+        path = write_manifest(slides, mode=mode)
+        self._paths.append(path)
+        return check_balance(path)
+
+    def _run_occ(self, slides, mode="hybrid"):
+        # 占空族逻辑测试：临时启用占空检测（默认停用），验证启用时判定仍正确。
+        with occupancy_enabled():
+            return self._run(slides, mode=mode)
+
+    def test_balanced_passes(self):
+        # 覆盖率高、四半区都有内容、无重叠 → 零 ERROR。
+        problems, _warn, _det = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5)])
+        self.assertEqual(problems, [], f"均衡页不应报缺陷：{problems}")
+
+    def test_overlap_always_error(self):
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_overlap_error_even_with_bg(self):
+        # 重叠不可降级：即便有全幅底图也必须 ERROR（封面撞车的克星）。
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP, has_bg=True)])
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_overlap_reports_normalized_coords(self):
+        # 用户要求：重叠为主门，报错带 元素 + 重叠范围 + 归一化坐标(0–1)。
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP_COORDS)])
+        p = next(x for x in problems if "相互叠加" in x)
+        self.assertIn("归一化", p, f"重叠消息应标明归一化坐标：{p}")
+        self.assertIn("重叠区", p, p)
+        # 归一化坐标数值出现（aRect.x=0.05 / rect.y=0.78）
+        self.assertIn("0.78", p, f"应含归一化坐标数值：{p}")
+
+    def test_overlap_without_coords_degrades_gracefully(self):
+        # 旧 manifest（无 aRect/bRect/rect）仍能报，只退化为元素名对、不抛。
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        p = next(x for x in problems if "相互叠加" in x)
+        self.assertIn("标题", p, p)
+        self.assertNotIn("归一化", p, f"无坐标字段时不应硬塞归一化串：{p}")
+
+    # ── 占空族逻辑（启用时正确性）：默认停用，这些测试经 _run_occ 临时启用占空检测验证逻辑本身。──
+    def test_empty_bottom_half_error(self):
+        # 上满下空（slide 3 那种）→ ERROR。coverage 设 0.6（远高于过空阈值）隔离「空半」与「过空」。
+        problems, _w, _d = self._run_occ([balance(0.6, 0.85, 0.02, 0.45, 0.45)])
+        self.assertTrue(any("失衡" in p and "下空上满" in p for p in problems), problems)
+
+    def test_empty_left_half_error(self):
+        # 左空右满（slide 4 那种）→ ERROR。coverage 0.6（远高于过空阈值）隔离「空半」与「过空」。
+        problems, _w, _d = self._run_occ([balance(0.6, 0.45, 0.45, 0.02, 0.8)])
+        self.assertTrue(any("失衡" in p and "左空右满" in p for p in problems), problems)
+
+    def test_single_sparse_page_is_warning_not_error(self):
+        # 启用占空时：单页过空、无底图 → **仅 WARNING + 记账**，不单页 ERROR。
+        problems, warnings, _d = self._run_occ([balance(0.20, 0.25, 0.25, 0.25, 0.25)])
+        self.assertFalse(any("过空" in p for p in problems), f"单页过空不应 ERROR：{problems}")
+        self.assertTrue(any("过空" in w for w in warnings), warnings)
+
+    def test_too_sparse_warns_with_bg(self):
+        # 过空但有全幅底图铺满 → WARNING（「有图不算空」）。
+        problems, warnings, _d = self._run_occ([balance(0.20, 0.25, 0.25, 0.25, 0.25, has_bg=True)])
+        self.assertFalse(any("过空" in p for p in problems), problems)
+        self.assertTrue(any("过空" in w for w in warnings), warnings)
+
+    def test_sparse_with_foreground_visual_downgrades(self):
+        # 「有图不算空」：过空但有前景视觉块（图/SVG/图标）→ WARNING 标「有底图/视觉元素」，不 ERROR。
+        problems, warnings, _d = self._run_occ([balance(0.20, 0.25, 0.25, 0.25, 0.25, has_fg_visual=True)])
+        self.assertFalse(any("过空" in p for p in problems), problems)
+        self.assertTrue(any("过空" in w and "视觉元素" in w for w in warnings), warnings)
+
+    def test_majority_empty_pages_warning(self):
+        # 「不能页页空」：过半有内容页都过空 → **WARNING（不再整体 ERROR）**（2026-06-19「加回但宽松」）。3 页全 0.20。
+        sparse = balance(0.20, 0.25, 0.25, 0.25, 0.25)
+        problems, warnings, _d = self._run_occ([sparse, sparse, sparse])
+        self.assertFalse(any("过半页面过空" in p for p in problems), f"过半页空应降为 WARNING：{problems}")
+        self.assertTrue(any("过半页面过空" in w for w in warnings), warnings)
+
+    def test_minority_empty_pages_no_overall_warning(self):
+        # 仅 1/3 过空（未过半）→ 无「过半页面过空」整体条目（单页那条仍是 WARNING）。
+        full = balance(0.55, 0.5, 0.5, 0.5, 0.5)
+        sparse = balance(0.20, 0.25, 0.25, 0.25, 0.25)
+        problems, warnings, _d = self._run_occ([full, full, sparse])
+        self.assertFalse(any("过半页面过空" in p for p in problems), problems)
+        self.assertFalse(any("过半页面过空" in w for w in warnings), warnings)
+
+    def test_coverage_above_min_not_flagged(self):
+        # 启用占空时：0.30 ≥ COVER_MIN(0.26) → 既不 ERROR 也不记过空账（给 AI 更大解空间）。
+        problems, warnings, _d = self._run_occ([balance(0.30, 0.5, 0.5, 0.5, 0.5)])
+        self.assertFalse(any("过空" in p for p in problems), problems)
+        self.assertFalse(any("过空" in w for w in warnings), f"0.30 ≥ 0.26 不应记过空：{warnings}")
+
+    # ── 空心卡片硬门（补 computeSlideBalance 只量外框的盲区，"卡片字小空多"的确定性牙齿）──
+    def test_hollow_card_error_with_coords(self):
+        # 纯文本卡 fill 0.13（真机 build_bak 11 页实测）→ ERROR，且报卡片归一化坐标 + 填充率%。
+        problems, _w, _d = self._run_occ([balance(0.66, 0.6, 0.6, 0.6, 0.6, cards=[card(0.13, x=0.05, y=0.15)])])
+        p = next((x for x in problems if "填充不足" in x), None)
+        self.assertIsNotNone(p, f"fill 0.13 应判空心卡片：{problems}")
+        self.assertIn("13%", p, f"应报实际填充率：{p}")
+        self.assertIn("0.15", p, f"应报卡片归一化坐标：{p}")
+        self.assertIn("归一化", p, p)
+
+    def test_filled_card_passes(self):
+        # 正常文字卡 fill 0.53（真机 build_bak 07 页实测）→ 不判空心。
+        problems, _w, _d = self._run_occ([balance(0.62, 0.6, 0.6, 0.6, 0.6, cards=[card(0.53)])])
+        self.assertFalse(any("填充不足" in p for p in problems), problems)
+
+    def test_hollow_card_downgrades_with_visual(self):
+        # 新策略（2026-06-17）：空心卡片**可降级**——有底图/前景视觉块时降 WARNING（别逼 AI 反复改装饰卡烧配额）。
+        problems, warnings, _d = self._run_occ([balance(0.66, 0.6, 0.6, 0.6, 0.6, cards=[card(0.13)], has_bg=True)])
+        self.assertFalse(any("填充不足" in p for p in problems), problems)
+        self.assertTrue(any("填充不足" in w for w in warnings), warnings)
+
+    def test_small_card_exempt_from_hollow(self):
+        # 小卡（引文/装饰条/药丸，面积 w×h < CARD_MIN_AREA_FRAC 0.06）豁免——空心门只抓「大卡装一句话」。
+        problems, warnings, _d = self._run_occ([balance(0.66, 0.6, 0.6, 0.6, 0.6, cards=[card(0.05, w=0.12, h=0.08)])])
+        self.assertFalse(any("填充不足" in p for p in problems), problems)
+        self.assertFalse(any("填充不足" in w for w in warnings), warnings)
+
+    # ── 文本裁切软门（导出会缩字/截断，提示但不拦）──
+    def test_text_clip_is_warning_not_error(self):
+        runs = [{"text": "思维导图", "overflowPx": 25, "rect": {"x": 0.79, "y": 0.56, "w": 0.05, "h": 0.03}}]
+        problems, warnings, _d = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5, overflow_runs=runs)])
+        self.assertFalse(any("裁切" in p for p in problems), f"文本裁切应是 WARNING 不是 ERROR：{problems}")
+        self.assertTrue(any("裁切" in w and "思维导图" in w for w in warnings), warnings)
+
+    def test_corner_cluster_error(self):
+        # 上空 + 左空 → 内容挤右下角 → ERROR（含「角」）。coverage 0.6（远高于过空阈值）隔离「挤角」与「过空」。
+        problems, _w, _d = self._run_occ([balance(0.6, 0.02, 0.5, 0.02, 0.5)])
+        self.assertTrue(any("角" in p for p in problems), problems)
+
+    def test_flat_mode_not_gated(self):
+        problems, warnings, _d = self._run([balance(0.1, 0.1, 0.0, 0.0, 0.1)], mode="flat")
+        self.assertEqual(problems, [], "flat 模式不应被构图闸门拦下")
+        self.assertTrue(any("flat" in w for w in warnings), warnings)
+
+    def test_message_is_report_first_then_optional_hint(self):
+        # 按用户原则（zod 式）：每条消息**先报问题**（【问题类型】… · 位置 · 范围 在最前），
+        # **修法降为清晰分隔的可选提示**（「｜可参考」前缀、不强制）。用重叠（始终 ERROR）验证。
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        p = next((x for x in problems if "相互叠加" in x), None)
+        self.assertIsNotNone(p, f"应报重叠 ERROR：{problems}")
+        self.assertTrue(p.startswith("【"), f"消息应以【问题类型】开头：{p}")
+        self.assertIn("｜可参考", p, f"修法应作为清晰分隔的可选提示：{p}")
+        self.assertLess(p.index("相互叠加"), p.index("｜可参考"), f"问题应在修法之前：{p}")
+
+    def test_hint_direction_overlap_move_first(self):
+        # 用户裁决的修法方向（2026-06-18，锁住、不许回退）：重叠/裁切 → **移动/重排 > 精炼文案 > 缩字（≤20%）**
+        #（配合全局放大字号要保大字号，移动提到精炼之前、缩字封 20% 顶；占空族已停用，不再有「空/空心卡」子段）。
+        # ── 重叠：移动 < 精炼 < 缩小字体，且含 20% ──
+        probs, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        ov = next((x for x in probs if "内容相互叠加" in x), None)
+        self.assertIsNotNone(ov, f"应报重叠：{probs}")
+        self.assertIn("移动", ov, f"重叠修法应以移动/重排打头：{ov}")
+        self.assertIn("20%", ov, f"缩字应封 20% 顶：{ov}")
+        self.assertLess(ov.index("移动"), ov.index("精炼"), f"移动应排在精炼之前：{ov}")
+        self.assertLess(ov.index("精炼"), ov.index("缩小字体"), f"精炼应排在缩字之前：{ov}")
+        # ── 文本裁切（始终保留）：加大框/挪位 < 精炼 < 缩小字体，且含 20% ──
+        _p, warns, _d = self._run([balance(
+            0.6, 0.5, 0.5, 0.5, 0.5,
+            overflow_runs=[{"text": "超长文案", "rect": {"x": 0.1, "y": 0.1, "w": 0.3, "h": 0.05}, "overflowPx": 40}],
+        )])
+        clip = next((x for x in warns if "文本裁切" in x), None)
+        self.assertIsNotNone(clip, f"应报文本裁切：{warns}")
+        self.assertIn("20%", clip)
+        self.assertLess(clip.index("加大框"), clip.index("精炼"), f"加大框/挪位应排在精炼之前：{clip}")
+        self.assertLess(clip.index("精炼"), clip.index("缩小字体"), f"精炼应排在缩字之前：{clip}")
+
+    # ── 占空族「加回但宽松」锁（默认 OCCUPANCY_CHECKS_ENABLED=True，2026-06-19）──
+    def test_occupancy_reenabled_lenient_by_default(self):
+        # 默认即启用：空半 / 挤角 等占空缺陷会被检测——但**有视觉元素时降 WARNING（不拦）**。
+        # 空半页 + 前景视觉块 → 应是 WARNING，不进 problems。
+        problems, warnings, _d = self._run([balance(0.6, 0.85, 0.02, 0.45, 0.45, has_fg_visual=True)])
+        self.assertFalse(any("失衡" in p for p in problems), f"有视觉应降 WARNING 不 ERROR：{problems}")
+        self.assertTrue(any("失衡" in w for w in warnings), f"占空族默认应启用并提示：{warnings}")
+
+    def test_occupancy_no_visual_still_error_by_default(self):
+        # 默认启用 + 无任何视觉（纯文字空半页）→ 仍 ERROR（「真空白才硬拦」）。
+        problems, _w, _d = self._run([balance(0.6, 0.85, 0.02, 0.45, 0.45)])
+        self.assertTrue(any("失衡" in p and "下空上满" in p for p in problems), problems)
+
+    def test_occupancy_can_be_fully_disabled(self):
+        # 「一键全停」仍可用：置 False 后占空族整族零 problem/zero warning（重叠/溢出/字号/夹带不受影响）。
+        with occupancy_disabled():
+            for b in (
+                balance(0.05, 0.0, 0.0, 0.0, 0.0),                 # 极空
+                balance(0.6, 0.85, 0.02, 0.45, 0.45),              # 空半（无视觉）
+                balance(0.6, 0.02, 0.5, 0.02, 0.5),                # 挤角
+                balance(0.66, 0.6, 0.6, 0.6, 0.6, cards=[card(0.13)]),  # 空心卡
+            ):
+                problems, warnings, _d = self._run([b])
+                for kw in ("过空", "失衡", "角", "填充不足", "过半"):
+                    self.assertFalse(any(kw in p for p in problems), f"停用后不应报 {kw}：{problems}")
+                    self.assertFalse(any(kw in w for w in warnings), f"停用后不应报 {kw}：{warnings}")
+
+    # ── 字号过小软门（放映级，WARNING 不拦）──
+    def test_small_font_is_warning(self):
+        st = [{"text": "图例标签", "fontSize": 18.0, "rect": {"x": 0.8, "y": 0.5, "w": 0.1, "h": 0.02}}]
+        problems, warnings, _d = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5, small_text=st)])
+        self.assertFalse(any("字号过小" in p for p in problems), f"字号过小应 WARNING 不 ERROR：{problems}")
+        self.assertTrue(any("字号过小" in w and "图例标签" in w and "18" in w for w in warnings), warnings)
+
+    # ── 截图夹带文本硬门（ERROR，与重叠同级——用户硬要求：底图/切图绝不能带 HTML/SVG 文本）──
+    def test_baked_text_dom_is_error(self):
+        bt = [{"text": "嫁接式架构", "source": "dom", "rect": {"x": 0.5, "y": 0.4, "w": 0.3, "h": 0.04}}]
+        problems, _w, _d = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5, baked_text=bt)])
+        p = next((x for x in problems if "截图夹带文本" in x), None)
+        self.assertIsNotNone(p, f"DOM 漏标文本应判截图夹带文本 ERROR：{problems}")
+        self.assertIn("嫁接式架构", p, p)
+
+    def test_baked_text_pseudo_is_error(self):
+        bt = [{"text": "新功能", "source": "pseudo", "rect": {"x": 0.1, "y": 0.1, "w": 0.1, "h": 0.03}}]
+        problems, _w, _d = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5, baked_text=bt)])
+        p = next((x for x in problems if "截图夹带文本" in x), None)
+        self.assertIsNotNone(p, f"::before/::after 文字应判截图夹带文本 ERROR：{problems}")
+        self.assertIn("DOM 文本节点", p, f"修法应指向改成真实 DOM 文本：{p}")
+
+    def test_baked_text_error_even_with_bg_and_disabled_occupancy(self):
+        # 截图夹带文本不可降级、不受占空开关影响：有底图 + 占空停用，仍 ERROR。
+        bt = [{"text": "权限说明", "source": "dom", "rect": {"x": 0.5, "y": 0.4, "w": 0.3, "h": 0.04}}]
+        with occupancy_disabled():
+            problems, _w, _d = self._run([balance(0.62, 0.5, 0.5, 0.5, 0.5, has_bg=True, baked_text=bt)])
+        self.assertTrue(any("截图夹带文本" in p for p in problems), problems)
+
+    def test_overlap_and_overflow_always_report(self):
+        # 重叠恒 ERROR、文本溢出恒 WARNING（与占空开关无关）。
+        probs, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        self.assertTrue(any("相互叠加" in p for p in probs), probs)
+        _p, warns, _d = self._run([balance(
+            0.6, 0.5, 0.5, 0.5, 0.5,
+            overflow_runs=[{"text": "超长", "rect": {"x": 0.1, "y": 0.1, "w": 0.3, "h": 0.05}, "overflowPx": 40}],
+        )])
+        self.assertTrue(any("文本裁切" in w for w in warns), warns)
+
+    # ── 超出画布软门（WARNING，与占空开关无关）──
+    def test_off_canvas_is_warning(self):
+        oc = [{"kind": "fg", "name": "fg-0-2", "rect": {"x": 0.55, "y": 0.06, "w": 0.39, "h": 1.17}}]  # y+h>1
+        problems, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=oc)])
+        self.assertFalse(any("超出画布" in p for p in problems), f"超画布应 WARNING 不 ERROR：{problems}")
+        self.assertTrue(any("超出画布" in w and "fg-0-2" in w for w in warnings), warnings)
+
+    def test_off_canvas_independent_of_occupancy_switch(self):
+        # 文本越界也报；且不受占空开关影响（停用占空后仍报）。
+        oc = [{"kind": "text", "name": "超长标题", "rect": {"x": 0.05, "y": 0.9, "w": 0.5, "h": 0.2}}]
+        with occupancy_disabled():
+            _p, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=oc)])
+        self.assertTrue(any("超出画布" in w and "超长标题" in w for w in warnings), warnings)
+
+    # ── 严重越界（catastrophic）：内容实质飞出画布（可见 < 20%，s9 事故）──
+    # s9 实测：轨道被大图撑爆，标题/正文全跑到 x≈0.99（可见 ~6%）。
+    S9_OFFCANVAS = [{"kind": "text", "name": "一台顶 N 台", "rect": {"x": 0.99, "y": 0.10, "w": 0.176, "h": 0.155}}]
+
+    def test_severe_offcanvas_default_still_warning(self):
+        # 默认（不传 strict）：即便严重越界也保持 WARNING —— 逐字节兼容旧行为，不误伤 webppt。
+        problems, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=self.S9_OFFCANVAS)])
+        self.assertFalse(any("超出画布" in p for p in problems), f"默认不应升 ERROR：{problems}")
+        self.assertTrue(any("超出画布" in w and "可见部分仅" in w for w in warnings), warnings)
+
+    def test_severe_offcanvas_strict_is_error(self):
+        # --strict-offcanvas：可见 < 20% 的越界升 ERROR，并标出可见比例。
+        path = write_manifest([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=self.S9_OFFCANVAS)])
+        self._paths.append(path)
+        problems, _w, _d = check_balance(path, strict_offcanvas=True)
+        p = next((x for x in problems if "超出画布" in x), None)
+        self.assertIsNotNone(p, f"严重越界 strict 应 ERROR：{problems}")
+        self.assertIn("可见部分仅", p, p)
+        self.assertIn("min-width:0", p, f"应提示轨道撑爆的治本修法：{p}")
+
+    def test_mild_offcanvas_strict_still_warning(self):
+        # 轻微越界（可见 > 20%）即便 strict 也只 WARNING —— 只硬拦「实质不可见」。
+        oc = [{"kind": "text", "name": "略越界", "rect": {"x": 0.05, "y": 0.9, "w": 0.5, "h": 0.2}}]  # 可见 ~50%
+        path = write_manifest([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=oc)])
+        self._paths.append(path)
+        problems, warnings, _d = check_balance(path, strict_offcanvas=True)
+        self.assertFalse(any("超出画布" in p for p in problems), f"轻微越界不应升 ERROR：{problems}")
+        self.assertTrue(any("超出画布" in w for w in warnings), warnings)
+
+    # ── content_boxes==0：无真实视觉 → ERROR；有真实底图/视觉 → WARNING（纯图封面合法）──
+    def test_empty_page_no_visual_is_error(self):
+        problems, _w, _d = self._run([balance(0.0, 0.0, 0.0, 0.0, 0.0, boxes=0)])
+        self.assertTrue(any("未量到内容" in p for p in problems), f"无视觉空页应 ERROR：{problems}")
+
+    def test_empty_page_with_real_bg_downgrades(self):
+        # 纯图封面合法：content_boxes==0 但有真实底图 → WARNING（依赖 Gap A：真背景才 hasBgImage=true）。
+        problems, warnings, _d = self._run([balance(0.0, 0.0, 0.0, 0.0, 0.0, boxes=0, has_bg=True)])
+        self.assertFalse(any("未量到内容" in p for p in problems), f"纯图封面不应 ERROR：{problems}")
+        self.assertTrue(any("未量到内容" in w for w in warnings), warnings)
+
+    # ── catastrophic_only：只报「内容不可见」，抑制良性重叠/占空噪声（visual_quality_gate 回归安全硬门）──
+    def test_catastrophic_only_suppresses_benign_overlap(self):
+        # 只有重叠（良性相邻/嵌套的高频误报）→ catastrophic_only 返回空，绝不误拦干净 deck。
+        path = write_manifest([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)])
+        self._paths.append(path)
+        problems, _w, _d = check_balance(path, catastrophic_only=True)
+        self.assertEqual(problems, [], f"catastrophic_only 不应被良性重叠触发：{problems}")
+
+    def test_catastrophic_only_catches_severe_offcanvas(self):
+        path = write_manifest([balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=self.S9_OFFCANVAS)])
+        self._paths.append(path)
+        problems, _w, _d = check_balance(path, catastrophic_only=True)
+        self.assertTrue(any("超出画布" in p for p in problems), f"严重越界应进 catastrophic：{problems}")
+
+    def test_catastrophic_only_catches_empty_no_visual(self):
+        path = write_manifest([balance(0.0, 0.0, 0.0, 0.0, 0.0, boxes=0)])
+        self._paths.append(path)
+        problems, _w, _d = check_balance(path, catastrophic_only=True)
+        self.assertTrue(any("未量到内容" in p for p in problems), f"无视觉空页应进 catastrophic：{problems}")
+
+    # ── 文字对比度不足：**一律 WARNING、绝不 ERROR**（硬门会逼弱模型改 HTML 改崩 → halt；治本在上游设计铁律）──
+    def test_low_contrast_severe_solid_is_warning_not_error(self):
+        # 深紫底黑字 ratio 1.1 + 纯底（最严重）也只 WARNING，不硬拦（防导出步被逼改 HTML 改崩 halt）。
+        problems, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, low_contrast=[lc(1.1, True)])])
+        self.assertFalse(any("对比度不足" in p for p in problems), f"对比度绝不 ERROR：{problems}")
+        w = next((x for x in warnings if "对比度不足" in x), None)
+        self.assertIsNotNone(w, f"应 WARNING 报对比度：{warnings}")
+        self.assertIn("1.1", w, w)
+
+    def test_low_contrast_low_confidence_is_warning(self):
+        # 渐变/图底（bgSolid=False）→ WARNING。
+        problems, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, low_contrast=[lc(1.5, False)])])
+        self.assertFalse(any("对比度不足" in p for p in problems), problems)
+        self.assertTrue(any("对比度不足" in w for w in warnings), warnings)
+
+    def test_low_contrast_never_error_regardless_of_occupancy(self):
+        # 对比度门恒为 WARNING、与占空开关无关：停用占空后严重低对比仍只 WARNING、不 ERROR。
+        with occupancy_disabled():
+            problems, warnings, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, low_contrast=[lc(1.1, True)])])
+        self.assertFalse(any("对比度不足" in p for p in problems), problems)
+        self.assertTrue(any("对比度不足" in w for w in warnings), warnings)
+
+    def test_no_occupancy_argument_path_disables_occupancy_family(self):
+        path = write_manifest([balance(0.20, 0.85, 0.02, 0.02, 0.85)])
+        self._paths.append(path)
+        problems, warnings, _d = check_balance(path, occupancy_checks_enabled=False)
+        combined = "\n".join(problems + warnings)
+        self.assertNotIn("过空", combined)
+        self.assertNotIn("失衡", combined)
+
+
+class LayoutReportResolveTest(unittest.TestCase):
+    """构图闸门前置到 HTML 层后，闸门读的是 export --measure-only 写的 layout-report.json
+    （与 export-manifest.json 同 schema）。锁两件事：① 传目录时优先 layout-report.json；
+    ② check_balance 在 layout-report.json 上判定与 manifest 完全一致。"""
+
+    def setUp(self):
+        self.dir = tempfile.mkdtemp()
+
+    def tearDown(self):
+        import shutil
+
+        shutil.rmtree(self.dir, ignore_errors=True)
+
+    def _write(self, name, mode="hybrid"):
+        # 02 页带重叠 → 始终 ERROR（占空族已停用，用重叠这条恒在的缺陷验证 report 被正确读取）。
+        report = {
+            "mode": mode,
+            "width": 1920,
+            "height": 1080,
+            "slides": [
+                {"index": 1, "label": "01 均衡页", "balance": balance(0.62, 0.5, 0.5, 0.5, 0.5)},
+                {"index": 2, "label": "02 重叠页", "balance": balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=OVERLAP)},
+            ],
+        }
+        path = os.path.join(self.dir, name)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(report, f)
+        return path
+
+    def test_dir_prefers_layout_report(self):
+        # 目录里同时有 layout-report.json 与 export-manifest.json → 优先前者（HTML 层廉价产物）。
+        self._write("export-manifest.json")
+        report_path = self._write("layout-report.json")
+        self.assertEqual(_resolve_manifest_path(self.dir), report_path)
+
+    def test_dir_falls_back_to_manifest(self):
+        # 只有 export-manifest.json（全量导出产物）→ 回落它。
+        manifest_path = self._write("export-manifest.json")
+        self.assertEqual(_resolve_manifest_path(self.dir), manifest_path)
+
+    def test_check_balance_on_layout_report(self):
+        # layout-report.json 与 manifest 同 schema：02 页重叠应被判 ERROR。
+        report_path = self._write("layout-report.json")
+        problems, _warn, _det = check_balance(report_path)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+
+# ── --ppt-strict（2026-07-02 逐页体检裁决）：默认关、webppt 行为不变；ppt 视觉门专用严格档。──
+# 噪声样本全部取自真机 deck 的 layout-report.json（57 条重叠逐条标定），阈值改动会破坏标定需重验。
+def _ov(a_rect, b_rect, rect, frac, a_kind="text", b_kind="text", a="甲", b="乙"):
+    return {"a": a, "b": b, "aKind": a_kind, "bKind": b_kind, "areaIn": 0.3,
+            "fracOfSmaller": frac, "aRect": a_rect, "bRect": b_rect, "rect": rect}
+
+
+# R1 行盒贴边：标题/副标题 0.01h 细带（真机 02 目录「目录」×「五章走完…」，frac 14%）
+NOISE_THIN = _ov({"x": 0.06, "y": 0.05, "w": 0.94, "h": 0.09},
+                 {"x": 0.06, "y": 0.14, "w": 0.94, "h": 0.06},
+                 {"x": 0.06, "y": 0.14, "w": 0.94, "h": 0.01}, 0.14)
+# R2 膨胀父盒包含：小框 95% 被 3.2× 大框含住（真机 02「行业真问题…」×「失全·失时…」）
+NOISE_CONTAIN = _ov({"x": 0.12, "y": 0.34, "w": 0.26, "h": 0.17},
+                    {"x": 0.12, "y": 0.43, "w": 0.27, "h": 0.05},
+                    {"x": 0.12, "y": 0.43, "w": 0.26, "h": 0.05}, 0.95)
+# R3 行盒尾部（纵向）：重叠落在文本框底部 33% 条带（真机 03「360°全景…」×fg-2-0，frac 85%）
+NOISE_VTAIL = _ov({"x": 0.06, "y": 0.53, "w": 0.63, "h": 0.21},
+                  {"x": 0.06, "y": 0.68, "w": 0.56, "h": 0.08},
+                  {"x": 0.06, "y": 0.68, "w": 0.56, "h": 0.07}, 0.85, b_kind="fg", b="fg-2-0")
+# R4 行盒尾部（横向）：短文字宽框右侧空白蹭相邻卡（真机 23「一套系统」×fg-22-1，frac 8%）
+NOISE_HTAIL = _ov({"x": 0.075, "y": 0.715, "w": 0.343, "h": 0.037},
+                  {"x": 0.39, "y": 0.693, "w": 0.322, "h": 0.123},
+                  {"x": 0.39, "y": 0.715, "w": 0.028, "h": 0.037}, 0.083, b_kind="fg", b="fg-22-1")
+# 真重叠 A：标题被卡遮挡（真机 09「系统总体架构」×fg-8-0，frac 22%、带高 0.04 不在尾部条带）
+REAL_TITLE_CARD = _ov({"x": 0.06, "y": 0.05, "w": 0.94, "h": 0.09},
+                      {"x": 0.06, "y": 0.10, "w": 0.37, "h": 0.18},
+                      {"x": 0.06, "y": 0.10, "w": 0.37, "h": 0.04}, 0.22, b_kind="fg", b="fg-8-0")
+# 真重叠 B：文字堆叠（真机 12「总师办…」×「异地专家…」，frac 88% 但大小框相当，R2 拦不住）
+REAL_STACKED = _ov({"x": 0.26, "y": 0.67, "w": 0.16, "h": 0.15},
+                   {"x": 0.26, "y": 0.69, "w": 0.15, "h": 0.15},
+                   {"x": 0.26, "y": 0.69, "w": 0.15, "h": 0.13}, 0.88)
+
+ALL_NOISE = [NOISE_THIN, NOISE_CONTAIN, NOISE_VTAIL, NOISE_HTAIL]
+
+
+class PptStrictTest(unittest.TestCase):
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _run(self, slides, **kw):
+        path = write_manifest(slides)
+        self._paths.append(path)
+        return check_balance(path, **kw)
+
+    def test_default_mode_still_reports_noise_overlaps(self):
+        # 红线锚：不带 ppt_strict 时四类噪声照报（webppt 依赖默认行为逐字节不变）。
+        problems, _w, _d = self._run([balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=ALL_NOISE)])
+        self.assertEqual(sum("相互叠加" in p for p in problems), 4, problems)
+
+    def test_strict_filters_all_four_noise_rules(self):
+        problems, _w, _d = self._run(
+            [balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=ALL_NOISE)], ppt_strict=True)
+        self.assertFalse(any("相互叠加" in p for p in problems), problems)
+
+    def test_strict_keeps_real_overlaps(self):
+        # 真碰撞（标题被卡压 / 文字堆叠）在噪声中幸存，照报 ERROR。
+        problems, _w, _d = self._run(
+            [balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=ALL_NOISE + [REAL_TITLE_CARD, REAL_STACKED])],
+            ppt_strict=True)
+        hits = [p for p in problems if "相互叠加" in p]
+        self.assertEqual(len(hits), 2, problems)
+        self.assertTrue(any("fg-8-0" in p for p in hits), hits)
+
+    def test_strict_offcanvas_partial_clip_is_error(self):
+        # 「内容超出 PPT 下边缘」：可见 35%（>20% 非 catastrophic）默认 WARNING、strict 升 ERROR。
+        oc = [{"kind": "text", "name": "质量追溯 · 工艺复盘",
+               "rect": {"x": 0.135, "y": 0.97, "w": 0.278, "h": 0.086}}]
+        problems_default, warn_default, _ = self._run(
+            [balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=oc)])
+        self.assertFalse(any("超出画布" in p for p in problems_default), problems_default)
+        self.assertTrue(any("超出画布" in w for w in warn_default), warn_default)
+        problems_strict, _w, _d = self._run(
+            [balance(0.6, 0.5, 0.5, 0.5, 0.5, off_canvas=oc)], ppt_strict=True)
+        self.assertTrue(any("超出画布" in p for p in problems_strict), problems_strict)
+
+    def test_strict_big_empty_card_is_error(self):
+        # 大空板（占页 33%、填充 0）：默认「有图可接受」WARNING → strict 升【空心大卡】ERROR。
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, cards=[card(0.0, w=0.368, h=0.904)],
+                    has_fg_visual=True)
+        b["mediaRects"] = []  # 有媒体信息、但没有媒体块盖住
+        with occupancy_enabled():
+            problems, _w, _d = self._run([b], ppt_strict=True)
+        self.assertTrue(any("空心大卡" in p for p in problems), problems)
+
+    def test_strict_media_covered_card_exempt(self):
+        # 图卡假空：媒体块盖住卡 ≥70%（slide15 网络立方体图卡）→ strict 下整条豁免（连 WARNING 都不留）。
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, cards=[card(0.0, x=0.68, y=0.30, w=0.26, h=0.65)],
+                    has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.68, "y": 0.30, "w": 0.26, "h": 0.65}]
+        with occupancy_enabled():
+            problems, warnings_, _d = self._run([b], ppt_strict=True)
+        self.assertFalse(any("空心大卡" in p for p in problems), problems)
+        self.assertFalse(any("填充不足" in w for w in warnings_), warnings_)
+
+    def test_strict_without_media_info_no_escalation(self):
+        # 旧 manifest（无 mediaRects 字段）：strict 不升级空卡（防误伤图卡），走默认 WARNING。
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, cards=[card(0.0, w=0.368, h=0.904)],
+                    has_fg_visual=True)
+        with occupancy_enabled():
+            problems, warnings_, _d = self._run([b], ppt_strict=True)
+        self.assertFalse(any("空心大卡" in p for p in problems), problems)
+        self.assertTrue(any("填充不足" in w for w in warnings_), warnings_)
+
+    def test_strict_midrange_fill_stays_warning(self):
+        # 填充 10%~28% 之间：strict 也只走默认 WARNING（升级只抓真空板）。
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, cards=[card(0.15, w=0.368, h=0.904)],
+                    has_fg_visual=True)
+        b["mediaRects"] = []
+        with occupancy_enabled():
+            problems, warnings_, _d = self._run([b], ppt_strict=True)
+        self.assertFalse(any("空心大卡" in p for p in problems), problems)
+        self.assertTrue(any("填充不足" in w for w in warnings_), warnings_)
+
+
+# ── 【文字溢出卡片】（仅 ppt_strict；2026-07-02 slide13 CTA 案）──
+# 卡内文字在重叠检查里是豁免项，「字顶出自家卡」此前不可见；本检查读顶层 textRuns（px）×
+# balance.fgRects（归一化）做 containment 判定。卡 fixture 取自真机 fg-12-3（frosted plate）。
+PLATE = {"name": "fg-12-3", "rect": {"x": 0.611, "y": 0.534, "w": 0.314, "h": 0.093}, "hasMedia": False}
+
+
+def run_px(x, y, w, h, parent="fg-12-3", text="请批准立项 · 沈阳泰科易"):
+    return {"text": text, "x": x, "y": y, "w": w, "h": h,
+            "fontSize": 24, "color": "rgb(255,255,255)", "bgColor": None,
+            "bgSolid": False, "fgParent": parent}
+
+
+class PptStrictTextEscapeTest(unittest.TestCase):
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _run_slide(self, text_runs, fg_rects, **kw):
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5)
+        if fg_rects is not None:
+            b["fgRects"] = fg_rects
+        fd, path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        manifest = {"mode": "hybrid", "width": 1920, "height": 1080,
+                    "slides": [{"index": 13, "label": "13 总结", "balance": b, "textRuns": text_runs}]}
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(manifest, f)
+        self._paths.append(path)
+        return check_balance(path, **kw)
+
+    def test_text_below_card_bottom_is_error(self):
+        # 文字底缘 0.667 超出卡底 0.627 约 43px（真机 CTA 形态）→ strict 下 ERROR + 报「下缘」。
+        problems, _w, _d = self._run_slide([run_px(1180, 580, 560, 140)], [PLATE], ppt_strict=True)
+        hits = [p for p in problems if "文字溢出卡片" in p]
+        self.assertEqual(len(hits), 1, problems)
+        self.assertIn("下缘", hits[0])
+        self.assertIn("fg-12-3", hits[0])
+
+    def test_text_inside_card_not_flagged(self):
+        problems, _w, _d = self._run_slide([run_px(1180, 585, 560, 85)], [PLATE], ppt_strict=True)
+        self.assertFalse(any("文字溢出卡片" in p for p in problems), problems)
+
+    def test_small_overhang_within_tolerance(self):
+        # 溢出 ~12.8px（0.0119 < 0.012 容差）= 行盒舍入噪声，不报。
+        problems, _w, _d = self._run_slide([run_px(1180, 585, 560, 105)], [PLATE], ppt_strict=True)
+        self.assertFalse(any("文字溢出卡片" in p for p in problems), problems)
+
+    def test_default_mode_never_reports_escape(self):
+        # 红线锚：不带 ppt_strict 时本检查完全不跑（webppt 等默认调用零影响）。
+        problems, warnings_, _d = self._run_slide([run_px(1180, 580, 560, 140)], [PLATE])
+        self.assertFalse(any("文字溢出卡片" in x for x in problems + warnings_), (problems, warnings_))
+
+    def test_old_report_without_fgrects_skipped(self):
+        # 旧 report（无 fgRects 字段）：静默跳过，不误报不崩。
+        problems, _w, _d = self._run_slide([run_px(1180, 580, 560, 140)], None, ppt_strict=True)
+        self.assertFalse(any("文字溢出卡片" in p for p in problems), problems)
+
+    def test_media_card_also_checked(self):
+        # 媒体卡（hasMedia=true，不在 cards[] 里）也能当父卡查——fgRects 含全部前景块正是为此。
+        media = dict(PLATE, hasMedia=True)
+        problems, _w, _d = self._run_slide([run_px(1180, 580, 560, 140)], [media], ppt_strict=True)
+        self.assertTrue(any("文字溢出卡片" in p for p in problems), problems)
+
+    def test_broken_link_overlap_gets_card_hint(self):
+        # fgParent 断链（wrapper 被当 run）时溢出以「text×fg 高包含重叠」形态暴露——
+        # strict 下该重叠消息追加「加大卡片或让文字换行收纳」方向提示。
+        ov = _ov({"x": 0.594, "y": 0.519, "w": 0.347, "h": 0.122},
+                 {"x": 0.611, "y": 0.534, "w": 0.314, "h": 0.093},
+                 {"x": 0.611, "y": 0.534, "w": 0.314, "h": 0.093}, 1.0,
+                 a_kind="text", b_kind="fg", a="请批准立项 · 沈阳泰", b="fg-12-3")
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=[ov])
+        fd, path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump({"mode": "hybrid", "width": 1920, "height": 1080,
+                       "slides": [{"index": 13, "label": "13 总结", "balance": b}]}, f)
+        self._paths.append(path)
+        problems, _w, _d = check_balance(path, ppt_strict=True)
+        hits = [p for p in problems if "相互叠加" in p]
+        self.assertEqual(len(hits), 1, problems)
+        self.assertIn("加大卡片或让文字换行收纳", hits[0])
+        # 默认档同一数据：照报重叠但不带该提示（行为不变）。
+        problems_default, _w2, _d2 = check_balance(path)
+        hits_default = [p for p in problems_default if "相互叠加" in p]
+        self.assertEqual(len(hits_default), 1, problems_default)
+        self.assertNotIn("加大卡片或让文字换行收纳", hits_default[0])
+
+
+class PptStrictOverlapV2Test(unittest.TestCase):
+    """R5 媒体卡内文字降 WARNING + R6 导出加宽框幻影剔除（2026-07-03 真机 03/09 页复盘）。"""
+
+    # 真机 03 页 caption 形态：「驾驶舱全景」88% 落在图卡 fg-2-0 内（fgParent 断链）。
+    CAPTION_TEXT = {"x": 0.07, "y": 0.66, "w": 0.31, "h": 0.04}
+    CAPTION_FG = {"x": 0.06, "y": 0.26, "w": 0.29, "h": 0.46}
+    # 真机 09 页副标题幻影形态：导出框 h0.202（真实行盒 h0.101 的 2×）压到下方表格卡。
+    INFLATED_TEXT = {"x": 0.058, "y": 0.178, "w": 0.70, "h": 0.202}
+    TABLE_FG = {"x": 0.058, "y": 0.305, "w": 0.454, "h": 0.442}
+
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _check(self, overlaps, fg_rects=None, text_runs=None, **kw):
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, overlaps=overlaps)
+        if fg_rects is not None:
+            b["fgRects"] = fg_rects
+        slide = {"index": 3, "label": "03 痛点", "balance": b}
+        if text_runs is not None:
+            slide["textRuns"] = text_runs
+        fd, path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump({"mode": "hybrid", "width": 1920, "height": 1080, "slides": [slide]}, f)
+        self._paths.append(path)
+        return check_balance(path, **kw)
+
+    def _caption_ov(self):
+        return _ov(self.CAPTION_TEXT, self.CAPTION_FG,
+                   {"x": 0.07, "y": 0.66, "w": 0.28, "h": 0.04}, 0.88,
+                   a_kind="text", b_kind="fg", a="驾驶舱全景", b="fg-2-0")
+
+    def test_r5_media_caption_downgraded_to_warning(self):
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": True}]
+        problems, warnings_, _d = self._check([self._caption_ov()], fg, ppt_strict=True)
+        self.assertFalse(any("相互叠加" in p for p in problems), problems)
+        hits = [w for w in warnings_ if "媒体卡内文字" in w]
+        self.assertEqual(len(hits), 1, warnings_)
+        self.assertIn("驾驶舱全景", hits[0])
+
+    def test_r5_bare_img_tag_counts_as_media(self):
+        # hasMedia 只查后代——裸 <img> 前景块恒 false（真机 03 页），靠加性 tag 字段识别。
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": False, "tag": "img"}]
+        problems, warnings_, _d = self._check([self._caption_ov()], fg, ppt_strict=True)
+        self.assertFalse(any("相互叠加" in p for p in problems), problems)
+        self.assertTrue(any("媒体卡内文字" in w for w in warnings_), warnings_)
+
+    def test_r5_non_media_card_stays_error(self):
+        # 不透明白卡盖字是像素门盲区——非媒体卡包含不降级，宁可误报。
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": False, "tag": "div"}]
+        problems, _w, _d = self._check([self._caption_ov()], fg, ppt_strict=True)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_r5_text_swallowing_card_stays_error(self):
+        # 反向（text⊃fg，slide13 CTA 真缺陷）不豁免。
+        big_text = {"x": 0.05, "y": 0.25, "w": 0.35, "h": 0.50}
+        ov = _ov(big_text, self.CAPTION_FG, self.CAPTION_FG, 1.0,
+                 a_kind="text", b_kind="fg", a="请批准立项", b="fg-2-0")
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": True}]
+        problems, _w, _d = self._check([ov], fg, ppt_strict=True)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_r5_partial_straddle_stays_error(self):
+        # 骑边（50% 压卡）是真缺陷，不豁免。
+        straddle = {"x": 0.07, "y": 0.70, "w": 0.31, "h": 0.08}  # 下半截出卡（卡底 0.72）
+        ov = _ov(straddle, self.CAPTION_FG,
+                 {"x": 0.07, "y": 0.70, "w": 0.28, "h": 0.02}, 0.35,
+                 a_kind="text", b_kind="fg", a="骑边文字", b="fg-2-0")
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": True}]
+        problems, _w, _d = self._check([ov], fg, ppt_strict=True)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def _inflated_ov(self):
+        return _ov(self.INFLATED_TEXT, self.TABLE_FG,
+                   {"x": 0.058, "y": 0.305, "w": 0.454, "h": 0.075}, 0.24,
+                   a_kind="text", b_kind="fg", a="核心投入 ≈ 3 万元，对应的是", b="fg-8-0")
+
+    def test_r6_inflation_phantom_dropped(self):
+        # 原始行盒 y193 h109（norm h0.101，底 0.279）根本够不到卡顶 0.305 → 幻影剔除。
+        raw = [{"text": "核心投入 ≈ 3 万元，对应的是单架数亿元飞机的", "x": 111, "y": 192, "w": 1200, "h": 109}]
+        problems, warnings_, _d = self._check([self._inflated_ov()], [], raw, ppt_strict=True)
+        self.assertFalse(any("相互叠加" in x for x in problems + warnings_), (problems, warnings_))
+
+    def test_r6_still_overlapping_raw_kept(self):
+        # 原始行盒确实压进卡内（h200 → 底 0.363 > 卡顶 0.305）→ 真重叠保留。
+        raw = [{"text": "核心投入 ≈ 3 万元，对应的是单架数亿元飞机的", "x": 111, "y": 192, "w": 1200, "h": 200}]
+        problems, _w, _d = self._check([self._inflated_ov()], [], raw, ppt_strict=True)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_r6_no_raw_match_behavior_unchanged(self):
+        # 找不到同原点原始行盒（旧报告/坐标漂移）→ 不动，照报。
+        raw = [{"text": "别的文字", "x": 500, "y": 800, "w": 300, "h": 50}]
+        problems, _w, _d = self._check([self._inflated_ov()], [], raw, ppt_strict=True)
+        self.assertTrue(any("相互叠加" in p for p in problems), problems)
+
+    def test_default_mode_unaffected(self):
+        # 红线锚：默认档（webppt）R5/R6 完全不参与——caption 重叠照报 ERROR、幻影也照报。
+        fg = [{"name": "fg-2-0", "rect": self.CAPTION_FG, "hasMedia": True}]
+        raw = [{"text": "核心投入 ≈ 3 万元，对应的是单架数亿元飞机的", "x": 111, "y": 192, "w": 1200, "h": 109}]
+        problems, warnings_, _d = self._check(
+            [self._caption_ov(), self._inflated_ov()], fg, raw)
+        self.assertEqual(sum(1 for p in problems if "相互叠加" in p), 2, problems)
+        self.assertFalse(any("媒体卡内文字" in w for w in warnings_), warnings_)
+
+
+# ── 信息集锦/综述型客户图槽位偏窄（is_dense_info + mediaRects.sourceFile；2026-07-07 p8 连续 3 次
+#    未达标后新增）：只在传入 source_layout_plan_path 且有 is_dense_info==true 条目时激活，webppt 无
+#    此文件恒不触发；只反查这类明确标记的图，不改写其它 display_role 既有的 min_canvas_fraction 面积语义。
+
+def write_source_layout_plan(images):
+    fd, path = tempfile.mkstemp(suffix=".json")
+    os.close(fd)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"has_source": True, "images": images}, f)
+    return path
+
+
+class DenseInfoWidthTest(unittest.TestCase):
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _plan(self, images):
+        path = write_source_layout_plan(images)
+        self._paths.append(path)
+        return path
+
+    def _run(self, slides, source_layout_plan_path=None):
+        path = write_manifest(slides)
+        self._paths.append(path)
+        return check_balance(path, source_layout_plan_path=source_layout_plan_path)
+
+    def test_dense_info_narrow_render_warns(self):
+        # 真机 p8 复刻：47%宽×26%高的槽（面积≈31%，压线满足通用 min_canvas_fraction=0.30），
+        # 但宽度仅 26% < DENSE_INFO_MIN_WIDTH_FRACTION(0.55) → 报窄槽 WARNING。
+        plan = self._plan([{
+            "file": "src_8.png", "enhanced_file": "enhanced_src_8.png",
+            "is_dense_info": True, "min_canvas_fraction": 0.30,
+        }])
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.26, "h": 0.30, "sourceFile": "enhanced_src_8.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=plan)
+        self.assertTrue(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+        self.assertTrue(any("src_8.png" in w for w in warnings_), warnings_)
+
+    def test_dense_info_wide_render_passes(self):
+        plan = self._plan([{
+            "file": "src_8.png", "enhanced_file": "enhanced_src_8.png",
+            "is_dense_info": True, "min_canvas_fraction": 0.30,
+        }])
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.62, "h": 0.30, "sourceFile": "enhanced_src_8.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=plan)
+        self.assertFalse(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+    def test_non_dense_info_image_not_checked(self):
+        # min_canvas_fraction 声明了但 is_dense_info 非 true → 不参与本检查（不重写既有面积语义）。
+        plan = self._plan([{
+            "file": "src_7.png", "enhanced_file": "enhanced_src_7.png",
+            "is_dense_info": False, "min_canvas_fraction": 0.30,
+        }])
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.10, "h": 0.10, "sourceFile": "enhanced_src_7.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=plan)
+        self.assertFalse(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+    def test_no_source_layout_plan_path_no_check(self):
+        # 不传路径（webppt 默认调用场景）→ 恒不触发，即便 mediaRects 带 sourceFile。
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.10, "h": 0.10, "sourceFile": "enhanced_src_8.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=None)
+        self.assertFalse(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+    def test_missing_plan_file_silently_skips(self):
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.10, "h": 0.10, "sourceFile": "enhanced_src_8.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path="/nonexistent/path.json")
+        self.assertFalse(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+    def test_media_rect_without_source_file_skipped(self):
+        plan = self._plan([{
+            "file": "src_8.png", "enhanced_file": "enhanced_src_8.png",
+            "is_dense_info": True, "min_canvas_fraction": 0.30,
+        }])
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.10, "h": 0.10}]  # 无 sourceFile（旧 manifest）
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=plan)
+        self.assertFalse(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+    def test_original_file_stem_also_matches(self):
+        # sourceFile 直接是原图文件名（非 enhanced_ 前缀）也能匹配。
+        plan = self._plan([{
+            "file": "src_8.png", "enhanced_file": "enhanced_src_8.png",
+            "is_dense_info": True, "min_canvas_fraction": 0.30,
+        }])
+        b = balance(0.6, 0.5, 0.5, 0.5, 0.5, has_fg_visual=True)
+        b["mediaRects"] = [{"x": 0.06, "y": 0.7, "w": 0.20, "h": 0.30, "sourceFile": "src_8.png"}]
+        _p, warnings_, _d = self._run([b], source_layout_plan_path=plan)
+        self.assertTrue(any("信息集锦图槽位偏窄" in w for w in warnings_), warnings_)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)