Upload folder using huggingface_hub

tests/infographic_regression/run.py

@@ -0,0 +1,359 @@
+"""
+Full-infographic regression for title width / clipping (Bug B).
+
+This is intentionally NOT a title-only test. It runs the real
+`infographics_generator.process()` path with a fixed input dataset and a fixed
+chart template, then measures the final composed SVG in Chrome.
+
+Comparison modes:
+  - after_A_legacy_font:
+      Current code with Bug A line-spacing fix, but font_metrics is monkey-
+      patched to the old Linux fallback behavior (missing Georgia/Times ->
+      LiberationSans). This simulates "After A, before Bug B".
+  - after_AB_current:
+      Current production behavior: font_metrics resolves via fontconfig and
+      SVG text alignment uses native text-anchor where possible.
+
+Usage:
+    PYTHONPATH=. python tests/infographic_regression/run.py
+
+Outputs:
+    tests/infographic_regression/results/<mode>/<case>/
+"""
+
+import json
+import os
+import random
+import shutil
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+os.chdir(ROOT)
+
+# Do not let the chart-type whitelist hide the fixed regression template.
+os.environ["ALLOWED_CHART_TYPES_FILE"] = str(
+    ROOT / "tests" / "infographic_regression" / "_no_chart_whitelist.json"
+)
+
+import numpy as np
+
+from modules.title_styler.infographic_title_generator import generate_title
+from modules.infographics_generator.parse_utils import convert_svg_to_html
+from modules.infographics_generator.screenshot_utils import get_driver
+
+
+ET.register_namespace("", "http://www.w3.org/2000/svg")
+RESULTS_ROOT = ROOT / "tests" / "infographic_regression" / "results"
+RUN100_BAD_SVG = (
+    ROOT
+    / "output"
+    / "run100"
+    / "1777364634_horizontal_group_bar_chart_03_Art_scenario_1_031622_28996"
+    / "chart.svg"
+)
+
+CASES = [
+    {
+        "case_id": "techjobs_horizontal_group_bar_right_elegant_stack",
+        "input": ROOT / "test_input_100" / "Art_scenario_1_031622_28996.json",
+        "chart_name": "horizontal_group_bar_chart_03",
+        # This is the exact title template/segmentation shape observed in the
+        # bad run100 SVG:
+        #   TECH JOB GROWTH IN       (Arial 18, letter-spacing .15)
+        #   Key U.S. Cities          (Georgia 32 bold)
+        #   long subtitle            (Arial 17)
+        #
+        # It is intentionally full-infographic, because title-only rendering
+        # cannot prove whether the final outer SVG viewport is wide enough.
+        "title_template": "right_elegant_stack",
+        "title_override": "TECH JOB GROWTH IN\nKey U.S. Cities",
+    }
+]
+
+
+def _legacy_sans_fallback_paths(self, font_family, font_weight, font_style):
+    is_bold = font_weight in ["bold", "bolder", "700", "800", "900"]
+    is_italic = font_style in ["italic", "oblique"]
+    if is_bold and is_italic:
+        lib = "LiberationSans-BoldItalic.ttf"
+        dejavu = "DejaVuSans-BoldOblique.ttf"
+    elif is_bold:
+        lib = "LiberationSans-Bold.ttf"
+        dejavu = "DejaVuSans-Bold.ttf"
+    elif is_italic:
+        lib = "LiberationSans-Italic.ttf"
+        dejavu = "DejaVuSans-Oblique.ttf"
+    else:
+        lib = "LiberationSans-Regular.ttf"
+        dejavu = "DejaVuSans.ttf"
+    return [
+        f"/usr/share/fonts/truetype/liberation2/{lib}",
+        f"/usr/share/fonts/truetype/liberation/{lib}",
+        f"/usr/share/fonts/truetype/dejavu/{dejavu}",
+    ]
+
+
+def configure_font_mode(mode: str):
+    import modules.title_styler.font_metrics as fm
+
+    fm._metrics_instance = None
+    fm._FC_MATCH_CACHE.clear()
+    if mode == "after_A_legacy_font":
+        os.environ["TITLE_STYLER_NATIVE_TEXT_ANCHOR"] = "0"
+        fm.FontMetrics._fc_match = lambda self, font_family, font_weight, font_style: None
+        fm.FontMetrics._get_generic_fallback_paths = _legacy_sans_fallback_paths
+    else:
+        os.environ["TITLE_STYLER_NATIVE_TEXT_ANCHOR"] = "1"
+
+
+def make_deterministic_title_batch(case: dict):
+    def deterministic_title_styler_process_batch(
+        input=None,
+        input_data=None,
+        max_widths=None,
+        text_align="left",
+        background_color="#FFFFFF",
+        dark=False,
+        show_embellishment=True,
+        show_sub_title=True,
+        font_family=None,
+        return_meta=False,
+    ):
+        if max_widths is None:
+            max_widths = [500]
+
+        data = input_data
+        title = data["titles"]["main_title"]
+        subtitle = data["titles"].get("sub_title") if show_sub_title else None
+        colors_key = "colors_dark" if dark else "colors"
+        colors = data[colors_key]["other"]
+
+        out = []
+        for max_width in max_widths:
+            results = generate_title(
+                title=case.get("title_override") or title,
+                description=subtitle,
+                primary_color=colors["primary"],
+                secondary_color=colors.get("secondary"),
+                background_color=background_color,
+                max_width=max_width,
+                alignment=text_align,
+                template_name=case["title_template"],
+                use_llm=False,
+            )
+            result = results[0]
+            meta = {
+                "template_name": result.get("template_name"),
+                "width": result.get("width"),
+                "height": result.get("height"),
+                "max_width_requested": max_width,
+                "text_align": text_align,
+            }
+            out.append((result["svg"], meta) if return_meta else result["svg"])
+        return out
+
+    return deterministic_title_styler_process_batch
+
+
+def locate_latest_subfolder(mode_dir: Path, case_id: str) -> Path:
+    candidates = [
+        p for p in mode_dir.iterdir()
+        if p.is_dir() and p.name.endswith(case_id)
+    ]
+    return max(candidates, key=lambda p: p.stat().st_mtime)
+
+
+def measure_final_svg(driver, svg_path: Path) -> dict:
+    html_path = svg_path.with_suffix(".measure.html")
+    convert_svg_to_html(str(svg_path), str(html_path))
+    driver.get(f"file://{html_path.resolve()}")
+    return driver.execute_script(
+        """
+        const svg = document.querySelector('svg');
+        const title = svg.querySelector('g[data-type="title"], g.text');
+        const root = svg.getBoundingClientRect();
+        const rel = (r) => ({
+          left: r.left - root.left,
+          right: r.right - root.left,
+          top: r.top - root.top,
+          bottom: r.bottom - root.top,
+          width: r.width,
+          height: r.height,
+        });
+        const titleRect = title ? rel(title.getBoundingClientRect()) : null;
+        const textRects = title ? [...title.querySelectorAll('text')].map(t => ({
+          text: t.textContent,
+          fontFamily: getComputedStyle(t).fontFamily,
+          fontSize: getComputedStyle(t).fontSize,
+          anchor: t.getAttribute('text-anchor'),
+          rect: rel(t.getBoundingClientRect()),
+        })) : [];
+        const maxRight = Math.max(...textRects.map(t => t.rect.right), titleRect ? titleRect.right : 0);
+        const minLeft = Math.min(...textRects.map(t => t.rect.left), titleRect ? titleRect.left : 0);
+        const maxBottom = Math.max(...textRects.map(t => t.rect.bottom), titleRect ? titleRect.bottom : 0);
+        const minTop = Math.min(...textRects.map(t => t.rect.top), titleRect ? titleRect.top : 0);
+        return {
+          svg: { width: root.width, height: root.height },
+          titleRect,
+          textRects,
+          titleBounds: { minLeft, maxRight, minTop, maxBottom },
+          overflow: {
+            left: Math.max(0, -minLeft),
+            right: Math.max(0, maxRight - root.width),
+            top: Math.max(0, -minTop),
+            bottom: Math.max(0, maxBottom - root.height),
+          },
+        };
+        """
+    )
+
+
+def run_case(mode: str, case: dict, driver) -> dict:
+    random.seed(20260525)
+    np.random.seed(20260525)
+    configure_font_mode(mode)
+
+    import modules.infographics_generator.infographics_generator as ig
+
+    ig.title_styler_process_batch = make_deterministic_title_batch(case)
+
+    mode_dir = RESULTS_ROOT / mode
+    case_output = mode_dir / f"{case['case_id']}.svg"
+    case_output.parent.mkdir(parents=True, exist_ok=True)
+    ok = ig.process(
+        input=str(case["input"]),
+        output=str(case_output),
+        base_url="",
+        api_key="",
+        chart_name=case["chart_name"],
+        chart_only=False,
+        output_png=True,
+    )
+    subfolder = locate_latest_subfolder(mode_dir, case["case_id"])
+    final_svg = subfolder / "chart.svg"
+    final_png = subfolder / "chart.png"
+    final_info = subfolder / "info.json"
+    measure = measure_final_svg(driver, final_svg)
+    meta = {
+        "mode": mode,
+        "case_id": case["case_id"],
+        "ok": bool(ok),
+        "subfolder": str(subfolder.relative_to(ROOT)),
+        "svg": str(final_svg.relative_to(ROOT)),
+        "png": str(final_png.relative_to(ROOT)),
+        "info": json.loads(final_info.read_text()),
+        "measure": measure,
+    }
+    (subfolder / "regression_meta.json").write_text(
+        json.dumps(meta, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return meta
+
+
+def _fixed_run100_title_svg() -> str:
+    input_data = json.loads(CASES[0]["input"].read_text(encoding="utf-8"))
+    configure_font_mode("after_AB_current")
+    result = generate_title(
+        title=CASES[0]["title_override"],
+        description=input_data["titles"]["sub_title"],
+        primary_color="#ee5f51",
+        secondary_color=None,
+        background_color="#F2EDEE",
+        max_width=433,
+        alignment="right",
+        template_name=CASES[0]["title_template"],
+        use_llm=False,
+    )[0]
+    return result["svg"]
+
+
+def run_run100_svg_fixture(driver) -> dict:
+    """Full-SVG regression anchored on the real bad run100 artifact."""
+    fixture_dir = RESULTS_ROOT / "run100_final_svg_fixture"
+    fixture_dir.mkdir(parents=True, exist_ok=True)
+
+    before_svg = fixture_dir / "after_A_run100_bad.svg"
+    shutil.copyfile(RUN100_BAD_SVG, before_svg)
+
+    root = ET.parse(RUN100_BAD_SVG).getroot()
+    ns = {"svg": "http://www.w3.org/2000/svg"}
+    title_group = root.find(".//svg:g[@data-type='title']", ns)
+    assert title_group is not None, "run100 fixture must contain a title group"
+    for child in list(title_group):
+        title_group.remove(child)
+
+    fixed_title_root = ET.fromstring(_fixed_run100_title_svg())
+    for child in list(fixed_title_root):
+        title_group.append(child)
+
+    after_svg = fixture_dir / "after_AB_current_title_replaced.svg"
+    ET.ElementTree(root).write(after_svg, encoding="unicode")
+
+    before_meta = {
+        "mode": "after_A_run100_bad",
+        "svg": str(before_svg.relative_to(ROOT)),
+        "measure": measure_final_svg(driver, before_svg),
+    }
+    after_meta = {
+        "mode": "after_AB_current_title_replaced",
+        "svg": str(after_svg.relative_to(ROOT)),
+        "measure": measure_final_svg(driver, after_svg),
+    }
+    before_right = before_meta["measure"]["overflow"]["right"]
+    after_right = after_meta["measure"]["overflow"]["right"]
+    assert before_right > 100, f"run100 fixture should reproduce Bug B, got {before_right}px"
+    assert after_right <= 1, f"Bug B fix should remove right overflow, got {after_right}px"
+    meta = {
+        "case_id": "run100_real_bad_svg_title_replacement",
+        "modes": {
+            "after_A_run100_bad": before_meta,
+            "after_AB_current_title_replaced": after_meta,
+        },
+    }
+    (fixture_dir / "regression_meta.json").write_text(
+        json.dumps(meta, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return meta
+
+
+def main():
+    if RESULTS_ROOT.exists():
+        shutil.rmtree(RESULTS_ROOT)
+    RESULTS_ROOT.mkdir(parents=True)
+
+    driver = get_driver()
+    summary = {"cases": []}
+    for case in CASES:
+        case_summary = {"case_id": case["case_id"], "modes": {}}
+        for mode in ["after_A_legacy_font", "after_AB_current"]:
+            meta = run_case(mode, case, driver)
+            case_summary["modes"][mode] = meta
+        summary["cases"].append(case_summary)
+    summary["cases"].append(run_run100_svg_fixture(driver))
+    driver.quit()
+
+    (RESULTS_ROOT / "summary.json").write_text(
+        json.dumps(summary, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+    for case_summary in summary["cases"]:
+        print(f"=== {case_summary['case_id']} ===")
+        for mode, meta in case_summary["modes"].items():
+            overflow = meta["measure"]["overflow"]
+            svg = meta["measure"]["svg"]
+            title_width = meta.get("info", {}).get("title_width", "-")
+            png = meta.get("png", "-")
+            print(
+                f"{mode:22s} svg={svg['width']:.0f}x{svg['height']:.0f} "
+                f"title_width={title_width} overflow={overflow} png={png}"
+            )
+
+
+if __name__ == "__main__":
+    main()

tests/test_polisher_chart_internal_slots.py

@@ -0,0 +1,415 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from lxml import etree
+from PIL import Image
+
+from modules.full_image_polisher.full_image_polisher import (
+    SLOT_GUIDED_PROMPT,
+    build_slot_guidance_artifacts,
+    collect_svg_slots,
+    polish_full_image,
+)
+from modules.slot_layout_planner.chart_sanitizer import is_chart_internal_slot, sanitize_chart_svg
+from modules.slot_layout_planner.planner import ProtectedRegion, _collect_protected_regions, _slots_from_layout_payload
+
+
+SYNTHETIC_SVG = """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100">
+  <g class="data-point" transform="translate(50,50)">
+    <circle class="point-mark" r="12" fill="#358"/>
+    <circle class="point-marker-interior asset-slot"
+      data-asset-slot="point-marker-interior"
+      data-slot-anchor="point-center"
+      data-collision-rule="clipped-within-marker-avoid-labels-axes"
+      r="7" fill="#fff"/>
+  </g>
+  <g class="asset-slot header-topic-art" data-asset-slot="header-topic-art" data-asset-bbox="6,6,20,20">
+    <rect x="6" y="6" width="20" height="20" fill="#ccc"/>
+  </g>
+</svg>
+"""
+
+
+def test_sanitizer_keeps_chart_internal_asset_slots(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    output_svg = tmp_path / "sanitized.svg"
+    report_path = tmp_path / "report.json"
+    input_svg.write_text(SYNTHETIC_SVG, encoding="utf-8")
+
+    sanitize_chart_svg(input_svg, output_svg, report_path=report_path)
+
+    sanitized = output_svg.read_text(encoding="utf-8")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert "point-marker-interior" in sanitized
+    assert "header-topic-art" not in sanitized
+    assert report["removed_by_reason"] == {"slot_metadata": 1}
+
+
+def test_sanitizer_keeps_descendants_inside_chart_internal_slot(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    output_svg = tmp_path / "sanitized.svg"
+    input_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+          <g data-asset-slot="row-icon" data-bbox="10,10,20,20">
+            <path id="reserved-child-line" class="reserved-asset-slot-placeholder-line" d="M 10 10 L 20 20"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+
+    sanitize_chart_svg(input_svg, output_svg)
+
+    sanitized = output_svg.read_text(encoding="utf-8")
+    assert "row-icon" in sanitized
+    assert "reserved-child-line" in sanitized
+
+
+def test_polisher_collects_chart_internal_slots(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    input_png = tmp_path / "input.png"
+    input_svg.write_text(SYNTHETIC_SVG, encoding="utf-8")
+    Image.new("RGB", (100, 100), "white").save(input_png)
+
+    slots = collect_svg_slots(input_svg, input_png, slot_padding_px=0)
+
+    assert [slot.slot_name for slot in slots] == ["point-marker-interior", "header-topic-art"]
+
+
+def test_protected_regions_override_edit_mask(tmp_path):
+    input_png = tmp_path / "input.png"
+    planned_svg = tmp_path / "planned.svg"
+    reference_map = tmp_path / "reference_element_map.json"
+    mask_path = tmp_path / "slot_mask.png"
+    overlay_path = tmp_path / "slot_overlay.png"
+    prompt_path = tmp_path / "slot_prompt.json"
+
+    Image.new("RGB", (100, 100), "white").save(input_png)
+    planned_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100">
+          <g data-asset-slot="chart_overlay_callout" data-planned-element="callout" data-bbox="20,20,60,60">
+            <rect x="20" y="20" width="60" height="60"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+    reference_map.write_text(
+        json.dumps(
+            {
+                "reserved_slots": [],
+                "protected_regions": [
+                    {
+                        "id": "PROTECT_01",
+                        "reason": "preserve nearby chart label",
+                        "bbox_px": [40, 40, 20, 20],
+                    }
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    build_slot_guidance_artifacts(
+        input_png=input_png,
+        svg_path=planned_svg,
+        reference_map=reference_map,
+        mask_path=mask_path,
+        overlay_path=overlay_path,
+        prompt_path=prompt_path,
+        slot_padding_px=0,
+        prompt_template=SLOT_GUIDED_PROMPT,
+    )
+
+    with Image.open(mask_path) as mask:
+        rgba = mask.convert("RGBA")
+        assert rgba.getpixel((30, 30))[3] == 0
+        assert rgba.getpixel((50, 50))[3] == 255
+
+
+def test_chart_internal_reference_slots_are_added_to_edit_mask(tmp_path):
+    input_png = tmp_path / "input.png"
+    planned_svg = tmp_path / "planned.svg"
+    reference_map = tmp_path / "reference_element_map.json"
+    mask_path = tmp_path / "slot_mask.png"
+    overlay_path = tmp_path / "slot_overlay.png"
+    prompt_path = tmp_path / "slot_prompt.json"
+
+    Image.new("RGB", (100, 100), "white").save(input_png)
+    planned_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100">
+          <rect x="0" y="0" width="100" height="100"/>
+        </svg>""",
+        encoding="utf-8",
+    )
+    reference_map.write_text(
+        json.dumps(
+            {
+                "reserved_slots": [],
+                "chart_internal_slots": [
+                    {
+                        "id": "CHART_ICON_01",
+                        "source_slot": "row-icon-1",
+                        "bbox_px": [40, 40, 20, 20],
+                        "semantic": "Generate a contained row icon.",
+                    }
+                ],
+                "protected_regions": [],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    slots, _ = build_slot_guidance_artifacts(
+        input_png=input_png,
+        svg_path=planned_svg,
+        reference_map=reference_map,
+        mask_path=mask_path,
+        overlay_path=overlay_path,
+        prompt_path=prompt_path,
+        slot_padding_px=0,
+        prompt_template=SLOT_GUIDED_PROMPT,
+    )
+
+    assert [slot.slot_name for slot in slots] == ["row-icon-1"]
+    prompt = json.loads(prompt_path.read_text(encoding="utf-8"))
+    assert prompt["chart_internal_slot_count"] == 1
+    with Image.open(mask_path) as mask:
+        rgba = mask.convert("RGBA")
+        assert rgba.getpixel((50, 50))[3] == 0
+        assert rgba.getpixel((20, 20))[3] == 255
+
+
+def test_planner_collects_chart_internal_slot_regions(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    input_png = tmp_path / "input.png"
+    input_svg.write_text(SYNTHETIC_SVG, encoding="utf-8")
+    Image.new("RGB", (100, 100), "white").save(input_png)
+
+    regions = _collect_protected_regions(input_svg, input_png, (100, 200, 500, 500), padding_px=0)
+
+    assert len(regions) == 1
+    assert regions[0].source_slot == "point-marker-interior"
+    assert regions[0].id == "CHART_ICON_01"
+    assert regions[0].bbox_px == (315, 415, 70, 70)
+
+
+def test_chart_internal_classifier_covers_common_template_icon_names():
+    protected_names = [
+        "x-category-logo",
+        "category_icon_slot",
+        "category-icon-badge",
+        "category_badge_symbol",
+        "measure-badge-icon",
+        "measure_pill_icon_slot",
+        "row-source-logo",
+        "row-icon",
+        "card-header-icon",
+        "item-icon",
+        "bar_icon_slot",
+        "row-badge",
+        "bubble_identity_icon_1",
+        "platform-icon",
+        "year-card-temporal-icon",
+        "rose-sector-texture",
+        "range-area-gap-annotation-icon",
+        "emissions-cue-endpoint",
+    ]
+    editable_names = [
+        "header-topic-art",
+        "summary-card-icon",
+        "bottom-hero-image",
+    ]
+
+    for name in protected_names:
+        elem = etree.Element("g", {"data-asset-slot": name})
+        assert is_chart_internal_slot(elem), name
+
+    for name in editable_names:
+        elem = etree.Element("g", {"data-asset-slot": name})
+        assert not is_chart_internal_slot(elem), name
+
+
+def test_sanitizer_keeps_ambiguous_slot_metadata_by_default(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    output_svg = tmp_path / "sanitized.svg"
+    report_path = tmp_path / "report.json"
+    input_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+          <g class="reserved-asset-slot" data-asset-slot="unknown-template-slot" data-bbox="10,10,20,20">
+            <rect x="10" y="10" width="20" height="20"/>
+          </g>
+          <g data-asset-slot="bottom-summary-icon" data-bbox="50,10,20,20">
+            <rect x="50" y="10" width="20" height="20"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+
+    sanitize_chart_svg(input_svg, output_svg, report_path=report_path)
+
+    sanitized = output_svg.read_text(encoding="utf-8")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert "unknown-template-slot" in sanitized
+    assert "bottom-summary-icon" not in sanitized
+    assert report["removed_by_reason"] == {"slot_metadata": 1}
+
+
+def test_sanitizer_keeps_data_bearing_descendants_inside_editable_slot(tmp_path):
+    input_svg = tmp_path / "input.svg"
+    output_svg = tmp_path / "sanitized.svg"
+    report_path = tmp_path / "report.json"
+    input_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+          <g class="reserved-asset-slot bottom-summary-icon" data-asset-slot="bottom-summary-icon">
+            <rect class="value-node" x="10" y="10" width="20" height="20"
+              data-group="Retail" data-value="42"/>
+          </g>
+          <g class="reserved-asset-slot bottom-summary-icon" data-asset-slot="bottom-summary-icon">
+            <rect id="placeholder-only" x="50" y="10" width="20" height="20"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+
+    sanitize_chart_svg(input_svg, output_svg, report_path=report_path)
+
+    sanitized = output_svg.read_text(encoding="utf-8")
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert "data-value=\"42\"" in sanitized
+    assert "placeholder-only" not in sanitized
+    assert report["removed_by_reason"] == {"slot_metadata": 1}
+
+
+def test_gpt_layout_payload_validation_avoids_chart_internal_slots():
+    internal = ProtectedRegion(
+        id="CHART_ICON_01",
+        reason="chart-internal icon/asset slot",
+        bbox_px=(100, 100, 40, 40),
+        source_slot="row-icon-1",
+    )
+
+    slots, background, meta = _slots_from_layout_payload(
+        {
+            "background": "#FFFFFF",
+            "design_rationale": "test",
+            "slots": [
+                {
+                    "id": "callout",
+                    "kind": "callout",
+                    "bbox_px": [95, 95, 60, 40],
+                    "may_overlap_chart": True,
+                    "element": "Generate a callout.",
+                    "anchor": "near chart",
+                    "collision_rule": "avoid row icon",
+                    "asset_source_policy": "llm_generated_text_and_shape",
+                    "slot_requirements": ["preserve chart values"],
+                }
+            ],
+        },
+        canvas_w=300,
+        canvas_h=300,
+        chart_bbox=(40, 40, 220, 180),
+        allow_chart_overlap=True,
+        chart_internal_slots=[internal],
+    )
+
+    assert background == "#FFFFFF"
+    assert len(slots) == 1
+    assert slots[0].bbox_px != (95, 95, 60, 40)
+    assert meta["validation_notes"][0]["reason"] == "nudged clear of chart_internal_slots"
+
+
+def test_pinco_backend_dry_run_builds_inpaint_artifacts(tmp_path):
+    input_png = tmp_path / "input.png"
+    planned_svg = tmp_path / "planned.svg"
+    output_png = tmp_path / "pinco_output.png"
+
+    Image.new("RGB", (100, 100), "white").save(input_png)
+    planned_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100">
+          <g data-asset-slot="planned-icon" data-bbox="20,20,30,30">
+            <rect x="20" y="20" width="30" height="30"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+
+    manifest = polish_full_image(
+        input_png=input_png,
+        output_png=output_png,
+        api_key=None,
+        base_url=None,
+        svg_path=planned_svg,
+        slot_guided=True,
+        dry_run=True,
+        image_backend="pinco",
+        slot_padding_px=0,
+    )
+
+    assert manifest["image_backend"] == "pinco"
+    assert manifest["model"] == "pinco"
+    with Image.open(manifest["pinco_mask"]) as mask:
+        mask_l = mask.convert("L")
+        assert mask_l.getpixel((25, 25)) == 255
+        assert mask_l.getpixel((10, 10)) == 0
+    with Image.open(manifest["pinco_foreground"]) as foreground:
+        rgba = foreground.convert("RGBA")
+        assert rgba.getpixel((25, 25))[3] == 0
+        assert rgba.getpixel((10, 10))[3] == 255
+
+
+def test_pinco_command_backend_runs_slot_polish_without_openai_key(tmp_path):
+    input_png = tmp_path / "input.png"
+    planned_svg = tmp_path / "planned.svg"
+    output_png = tmp_path / "pinco_output.png"
+    stub = tmp_path / "pinco_stub.py"
+
+    Image.new("RGB", (100, 100), "white").save(input_png)
+    planned_svg.write_text(
+        """<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100">
+          <g data-asset-slot="planned-icon" data-bbox="20,20,30,30">
+            <rect x="20" y="20" width="30" height="30"/>
+          </g>
+        </svg>""",
+        encoding="utf-8",
+    )
+    stub.write_text(
+        """import argparse
+from PIL import Image, ImageDraw
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--input", required=True)
+parser.add_argument("--mask", required=True)
+parser.add_argument("--prompt-file", required=True)
+parser.add_argument("--output", required=True)
+args = parser.parse_args()
+with Image.open(args.input) as image:
+    out = image.convert("RGBA")
+draw = ImageDraw.Draw(out)
+draw.rectangle((20, 20, 50, 50), fill=(12, 34, 56, 255))
+out.save(args.output)
+""",
+        encoding="utf-8",
+    )
+
+    manifest = polish_full_image(
+        input_png=input_png,
+        output_png=output_png,
+        api_key=None,
+        base_url=None,
+        svg_path=planned_svg,
+        slot_guided=True,
+        dry_run=False,
+        resize_to_input=True,
+        image_backend="pinco",
+        pinco_command=f"{sys.executable} {stub} --input {{input}} --mask {{mask}} --prompt-file {{prompt_file}} --output {{output}}",
+        slot_padding_px=0,
+    )
+
+    assert manifest["image_backend"] == "pinco"
+    assert manifest["pinco_call_mode"] == "command"
+    assert output_png.is_file()
+    with Image.open(output_png) as output:
+        assert output.size == (100, 100)
+        assert output.convert("RGBA").getpixel((25, 25)) == (12, 34, 56, 255)

tests/title_styler_regression/run.py

@@ -0,0 +1,221 @@
+"""
+title_styler 回归测试集 driver。
+
+特性:
+  - 不调 LLM (use_llm=False, template_name= 指定) → 完全 deterministic
+  - 一次跑遍 PROBLEMATIC_CASES + FULL_TEMPLATE_TEST_CASES 30+ 个 case
+  - 同时输出 SVG (styler 直接产物) 和 PNG (Selenium 渲染, overlap-fix 关闭)
+  - PNG 用同一渲染管线 (modules.infographics_generator.screenshot_utils) → 跟最终产物一致
+  - 输出按 run_name 分桶，方便 baseline / after_fix 对比
+
+用法:
+    PYTHONPATH=. python tests/title_styler_regression/run.py --run baseline
+    # 改完代码再跑:
+    PYTHONPATH=. python tests/title_styler_regression/run.py --run after_fix
+    # 对比:
+    PYTHONPATH=. python tests/title_styler_regression/run.py --diff baseline after_fix
+
+输出:
+    tests/title_styler_regression/results/<run>/<case_id>/{title.svg, title.png, meta.json}
+    tests/title_styler_regression/results/<run>/summary.json
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+import time
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, ROOT)
+os.chdir(ROOT)
+
+from modules.title_styler.test_cases import PROBLEMATIC_CASES, FULL_TEMPLATE_TEST_CASES
+from modules.title_styler.infographic_title_generator import generate_title
+from modules.infographics_generator.screenshot_utils import get_driver, take_screenshot
+from modules.infographics_generator.parse_utils import convert_svg_to_html
+
+RESULTS_ROOT = os.path.join("tests", "title_styler_regression", "results")
+
+
+def _safe_id(s: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9._-]+", "_", s)[:80]
+
+
+def _font_size_histogram(svg_text: str) -> dict:
+    hist = {}
+    for s in re.findall(r"font-size[=:]\s*[\"']?(\d+(?:\.\d+)?)", svg_text):
+        hist[s] = hist.get(s, 0) + 1
+    return hist
+
+
+def collect_cases():
+    """合并去重；每个 case 用 (test_id + template_name + 前 30 char title) 作为 key。"""
+    seen = set()
+    out = []
+    for src_name, src in [
+        ("problematic", PROBLEMATIC_CASES),
+        ("full", FULL_TEMPLATE_TEST_CASES),
+    ]:
+        for c in src:
+            key = (c["test_id"], c["template_name"], c["title_segments"][:30])
+            if key in seen:
+                continue
+            seen.add(key)
+            c2 = dict(c)
+            c2["__source__"] = src_name
+            out.append(c2)
+    return out
+
+
+def render_one(driver, case, run_dir):
+    case_id = _safe_id(f'{case["template_name"]}__{case["test_id"]}')
+    case_dir = os.path.join(run_dir, case_id)
+    os.makedirs(case_dir, exist_ok=True)
+
+    t0 = time.time()
+    results = generate_title(
+        title=case["title_segments"],
+        description=case["description"],
+        primary_color=case["primary_color"],
+        background_color=case["background_color"],
+        template_name=case["template_name"],
+        max_width=900,
+        use_llm=False,
+    )
+    styler_ms = (time.time() - t0) * 1000
+
+    if not results:
+        print(f"  FAIL no-svg: {case_id}", flush=True)
+        return {
+            "case_id": case_id,
+            "ok": False,
+            "reason": "generate_title returned empty",
+        }
+
+    r = results[0]
+    svg_text = r["svg"]
+    svg_path = os.path.join(case_dir, "title.svg")
+    with open(svg_path, "w", encoding="utf-8") as f:
+        f.write(svg_text)
+
+    html_path = os.path.join(case_dir, "render.html")
+    convert_svg_to_html(svg_path, html_path)
+    t1 = time.time()
+    take_screenshot(driver, html_path, resolve_text_overlap=False)
+    render_ms = (time.time() - t1) * 1000
+    rendered_png = html_path.replace(".html", ".png")
+    final_png = os.path.join(case_dir, "title.png")
+    shutil.move(rendered_png, final_png)
+
+    meta = {
+        "case_id": case_id,
+        "ok": True,
+        "test_id": case["test_id"],
+        "template_name": case["template_name"],
+        "title_segments": case["title_segments"],
+        "description": case["description"],
+        "primary_color": case["primary_color"],
+        "background_color": case["background_color"],
+        "styler_ms": round(styler_ms, 1),
+        "render_ms": round(render_ms, 1),
+        "svg_width": r.get("width"),
+        "svg_height": r.get("height"),
+        "font_size_hist": _font_size_histogram(svg_text),
+        "source_suite": case["__source__"],
+    }
+    with open(os.path.join(case_dir, "meta.json"), "w", encoding="utf-8") as f:
+        json.dump(meta, f, indent=2, ensure_ascii=False)
+    print(
+        f"  OK  {case_id:60s}  {r['width']}x{r['height']}px  "
+        f"styler={styler_ms:.0f}ms render={render_ms:.0f}ms",
+        flush=True,
+    )
+    return meta
+
+
+def run(run_name: str, only: str = None):
+    cases = collect_cases()
+    if only:
+        cases = [c for c in cases if only in c["template_name"] or only in c["test_id"]]
+    if not cases:
+        print("no cases matched", flush=True)
+        return
+
+    run_dir = os.path.join(RESULTS_ROOT, run_name)
+    if os.path.exists(run_dir):
+        print(f"clearing {run_dir}", flush=True)
+        shutil.rmtree(run_dir)
+    os.makedirs(run_dir, exist_ok=True)
+
+    print(f"=== run '{run_name}' on {len(cases)} cases ===", flush=True)
+    driver = get_driver()
+    metas = []
+    for i, case in enumerate(cases, 1):
+        print(f"[{i}/{len(cases)}]", flush=True)
+        meta = render_one(driver, case, run_dir)
+        metas.append(meta)
+    driver.quit()
+
+    summary = {
+        "run_name": run_name,
+        "n_cases": len(metas),
+        "n_ok": sum(1 for m in metas if m.get("ok")),
+        "n_fail": sum(1 for m in metas if not m.get("ok")),
+        "cases": metas,
+    }
+    with open(os.path.join(run_dir, "summary.json"), "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=2, ensure_ascii=False)
+    print(
+        f"\n=== run '{run_name}' done. ok={summary['n_ok']} fail={summary['n_fail']} ===",
+        flush=True,
+    )
+    print(f"results in: {run_dir}/")
+
+
+def diff(run_a: str, run_b: str):
+    dir_a = os.path.join(RESULTS_ROOT, run_a)
+    dir_b = os.path.join(RESULTS_ROOT, run_b)
+    sa = json.load(open(os.path.join(dir_a, "summary.json")))
+    sb = json.load(open(os.path.join(dir_b, "summary.json")))
+    map_a = {c["case_id"]: c for c in sa["cases"]}
+    map_b = {c["case_id"]: c for c in sb["cases"]}
+    all_ids = sorted(set(map_a) | set(map_b))
+    print(f"=== diff {run_a} vs {run_b} ===")
+    print(
+        f"{'case':70s}  {'svg WxH (a)':>18s}  {'svg WxH (b)':>18s}  {'dh':>5s}  {'fonts a/b'}"
+    )
+    for cid in all_ids:
+        a, b = map_a.get(cid), map_b.get(cid)
+        if a and a.get("ok") and b and b.get("ok"):
+            wa, ha = a["svg_width"], a["svg_height"]
+            wb, hb = b["svg_width"], b["svg_height"]
+            dh = hb - ha
+            fa = sorted(a["font_size_hist"].keys(), key=float)
+            fb = sorted(b["font_size_hist"].keys(), key=float)
+            flag = "" if dh == 0 else (" *" if abs(dh) >= 4 else "")
+            print(
+                f"{cid:70s}  {wa}x{ha:>4d}     {wb}x{hb:>4d}    {dh:+5d}  "
+                f"{','.join(fa)} / {','.join(fb)}{flag}"
+            )
+        else:
+            print(f"{cid:70s}  (missing or failed in one run)")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--run", help="run a regression pass with this name (e.g. baseline, after_fix)")
+    g.add_argument("--diff", nargs=2, metavar=("RUN_A", "RUN_B"), help="diff two runs")
+    ap.add_argument("--only", help="filter cases whose template_name or test_id contains this substring")
+    args = ap.parse_args()
+    if args.run:
+        run(args.run, only=args.only)
+    else:
+        diff(args.diff[0], args.diff[1])
+
+
+if __name__ == "__main__":
+    main()

tests/title_styler_regression/viewer.py

@@ -0,0 +1,321 @@
+"""
+为 title_styler 回归测试结果生成一个零依赖前端 (viewer.html)。
+
+工作流:
+    PYTHONPATH=. python tests/title_styler_regression/run.py --run baseline
+    PYTHONPATH=. python tests/title_styler_regression/run.py --run after_fix
+    PYTHONPATH=. python tests/title_styler_regression/viewer.py
+    # 然后浏览器打开 tests/title_styler_regression/viewer.html
+
+特性:
+- 扫描 results/<run>/summary.json 自动发现所有 run
+- 顶部两个 dropdown 选 左/右 run, 一键切换
+- 每个 case 一行: 左 PNG | 右 PNG | meta (尺寸、字号、dh)
+- 支持按 |dh| 排序、按模板名 / test_id 过滤
+- 仅生成一个 HTML 文件 (相对路径引用 PNG), file:// 协议可直接打开
+"""
+
+import base64
+import json
+import os
+import sys
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+HERE = os.path.abspath(os.path.dirname(__file__))
+RESULTS_ROOT = os.path.join(HERE, "results")
+OUT_HTML = os.path.join(HERE, "viewer.html")
+
+
+def discover_runs():
+    runs = {}
+    if not os.path.isdir(RESULTS_ROOT):
+        return runs
+    for entry in sorted(os.listdir(RESULTS_ROOT)):
+        run_dir = os.path.join(RESULTS_ROOT, entry)
+        summary_path = os.path.join(run_dir, "summary.json")
+        if not os.path.isfile(summary_path):
+            continue
+        with open(summary_path, encoding="utf-8") as f:
+            summary = json.load(f)
+        cases = {}
+        for c in summary.get("cases", []):
+            cid = c.get("case_id")
+            if not cid:
+                continue
+            png_rel = os.path.relpath(
+                os.path.join(run_dir, cid, "title.png"), start=HERE
+            )
+            svg_rel = os.path.relpath(
+                os.path.join(run_dir, cid, "title.svg"), start=HERE
+            )
+            png_exists = os.path.isfile(os.path.join(HERE, png_rel))
+            cases[cid] = {
+                "ok": c.get("ok", False),
+                "reason": c.get("reason"),
+                "png": png_rel if png_exists else None,
+                "svg": svg_rel,
+                "w": c.get("svg_width"),
+                "h": c.get("svg_height"),
+                "fonts": c.get("font_size_hist", {}),
+                "test_id": c.get("test_id"),
+                "template": c.get("template_name"),
+                "title": c.get("title_segments"),
+                "description": c.get("description"),
+            }
+        runs[entry] = {
+            "n_ok": summary.get("n_ok", 0),
+            "n_fail": summary.get("n_fail", 0),
+            "cases": cases,
+        }
+    return runs
+
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<title>title_styler regression viewer</title>
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 13px/1.4 -apple-system, BlinkMacSystemFont, sans-serif; background: #f6f7f9; color: #222; }
+  header { position: sticky; top: 0; background: #1f2937; color: #fff; padding: 10px 16px; z-index: 10;
+           box-shadow: 0 1px 4px rgba(0,0,0,.15); }
+  header h1 { font-size: 14px; margin: 0 0 6px; font-weight: 600; letter-spacing: .3px; }
+  .controls { display: flex; gap: 14px; flex-wrap: wrap; align-items: center; font-size: 12px; }
+  .controls label { color: #cbd5e1; }
+  select, input[type=text] { background: #374151; color: #fff; border: 1px solid #4b5563;
+                              border-radius: 4px; padding: 4px 8px; font: inherit; }
+  select:focus, input:focus { outline: 2px solid #60a5fa; }
+  .badge { background: #374151; padding: 2px 8px; border-radius: 10px; color: #e5e7eb; }
+  .badge.up   { background: #14532d; color: #bbf7d0; }
+  .badge.down { background: #7f1d1d; color: #fecaca; }
+  .badge.zero { background: #374151; color: #9ca3af; }
+  main { padding: 14px; }
+  .summary { background: #fff; padding: 10px 14px; border-radius: 6px; margin-bottom: 12px;
+             box-shadow: 0 1px 2px rgba(0,0,0,.06); font-size: 12px; color: #4b5563;
+             display: flex; gap: 18px; flex-wrap: wrap; }
+  .row { background: #fff; border-radius: 6px; margin-bottom: 12px; padding: 10px;
+         box-shadow: 0 1px 2px rgba(0,0,0,.06); }
+  .row.changed { box-shadow: 0 0 0 2px #fbbf24, 0 1px 2px rgba(0,0,0,.06); }
+  .row-head { display: flex; gap: 10px; align-items: center; font-weight: 600; margin-bottom: 8px;
+              padding-bottom: 6px; border-bottom: 1px solid #e5e7eb; flex-wrap: wrap; }
+  .row-head .case-id { color: #1f2937; font-size: 13px; }
+  .row-head .pill { font-size: 11px; padding: 1px 6px; border-radius: 8px;
+                    background: #eef2ff; color: #3730a3; font-weight: 500; }
+  .row-head .pill.tpl { background: #ecfeff; color: #155e75; }
+  .row-meta { font-size: 11px; color: #6b7280; font-weight: 400; }
+  .pair { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+  .panel { background: #fafbfc; border: 1px solid #e5e7eb; border-radius: 4px; padding: 8px; }
+  .panel .head { font-size: 11px; color: #6b7280; margin-bottom: 6px; display: flex; justify-content: space-between; }
+  .panel img { display: block; max-width: 100%; height: auto;
+               background-image: repeating-conic-gradient(#f3f4f6 0 25%, #fff 0 50%);
+               background-size: 16px 16px; }
+  .panel.missing { background: #fef2f2; border-color: #fecaca; color: #991b1b; padding: 18px; text-align: center; }
+  .fonts { font-family: ui-monospace, SF Mono, Menlo, monospace; font-size: 11px; color: #1f2937; }
+  details { margin-top: 6px; }
+  details > summary { cursor: pointer; color: #4b5563; font-size: 11px; }
+  details pre { background: #f3f4f6; padding: 6px 8px; border-radius: 4px; overflow: auto;
+                font: 11px ui-monospace, monospace; margin: 6px 0 0; }
+  .empty { text-align: center; color: #6b7280; padding: 60px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>title_styler regression viewer</h1>
+  <div class="controls">
+    <label>left run <select id="runA"></select></label>
+    <label>right run <select id="runB"></select></label>
+    <label>filter <input type="text" id="filter" placeholder="template / test_id"></label>
+    <label>sort <select id="sort">
+      <option value="abs_dh_desc">|dh| desc (changed first)</option>
+      <option value="dh_desc">dh desc</option>
+      <option value="dh_asc">dh asc</option>
+      <option value="case_id">case_id</option>
+    </select></label>
+    <label><input type="checkbox" id="onlyChanged"> only changed (|dh|≥1)</label>
+    <span class="badge" id="counts"></span>
+  </div>
+</header>
+<main>
+  <div class="summary" id="summary"></div>
+  <div id="grid"></div>
+</main>
+
+<script>
+const RUNS = __RUNS_JSON__;
+
+function caseIds(run) {
+  return run ? Object.keys(run.cases) : [];
+}
+
+function pickDefaults() {
+  const names = Object.keys(RUNS);
+  if (names.length === 0) return [null, null];
+  if (names.length === 1) return [names[0], names[0]];
+  const afterAIdx = names.indexOf('after_fix');
+  const preferredB = [
+    'after_fix_linegap_tune',
+    'after_fix_bg_width',
+    'after_fix_desc_gap',
+    'after_fix_AB_anchor',
+    'after_fix_AB',
+  ].find(n => names.includes(n));
+  const preferredBIdx = preferredB ? names.indexOf(preferredB) : -1;
+  const a = afterAIdx >= 0 ? names[afterAIdx] : names[0];
+  const b = preferredBIdx >= 0 ? names[preferredBIdx] : names[1];
+  return [a, b];
+}
+
+function fontsHistToString(h) {
+  if (!h) return '';
+  return Object.keys(h).sort((a,b)=>parseFloat(a)-parseFloat(b)).map(k => `${k}×${h[k]}`).join(' ');
+}
+
+function classifyDh(dh) {
+  if (dh > 0) return 'up';
+  if (dh < 0) return 'down';
+  return 'zero';
+}
+
+function render() {
+  const aName = document.getElementById('runA').value;
+  const bName = document.getElementById('runB').value;
+  const runA = RUNS[aName] || { cases: {} };
+  const runB = RUNS[bName] || { cases: {} };
+  const filterStr = document.getElementById('filter').value.trim().toLowerCase();
+  const sortBy = document.getElementById('sort').value;
+  const onlyChanged = document.getElementById('onlyChanged').checked;
+  const allIds = Array.from(new Set([...caseIds(runA), ...caseIds(runB)]));
+
+  let rows = allIds.map(cid => {
+    const a = runA.cases[cid];
+    const b = runB.cases[cid];
+    const dh = (a && b && a.ok && b.ok) ? (b.h - a.h) : 0;
+    return { cid, a, b, dh };
+  });
+
+  if (filterStr) {
+    rows = rows.filter(r => r.cid.toLowerCase().includes(filterStr));
+  }
+  if (onlyChanged) {
+    rows = rows.filter(r => Math.abs(r.dh) >= 1);
+  }
+
+  switch (sortBy) {
+    case 'abs_dh_desc': rows.sort((x,y) => Math.abs(y.dh) - Math.abs(x.dh) || x.cid.localeCompare(y.cid)); break;
+    case 'dh_desc':     rows.sort((x,y) => y.dh - x.dh); break;
+    case 'dh_asc':      rows.sort((x,y) => x.dh - y.dh); break;
+    case 'case_id':     rows.sort((x,y) => x.cid.localeCompare(y.cid)); break;
+  }
+
+  const summaryEl = document.getElementById('summary');
+  const ups   = rows.filter(r => r.dh > 0).length;
+  const downs = rows.filter(r => r.dh < 0).length;
+  const zeros = rows.filter(r => r.dh === 0).length;
+  const max   = Math.max(0, ...rows.map(r => Math.abs(r.dh)));
+  summaryEl.innerHTML =
+    `<span><b>${rows.length}</b> cases shown</span>` +
+    `<span class="badge up">↑ taller: ${ups}</span>` +
+    `<span class="badge down">↓ shorter: ${downs}</span>` +
+    `<span class="badge zero">– unchanged: ${zeros}</span>` +
+    `<span>max |Δh| = <b>${max}</b>px</span>` +
+    `<span>left = <b>${aName}</b> · right = <b>${bName}</b></span>`;
+
+  const grid = document.getElementById('grid');
+  if (rows.length === 0) {
+    grid.innerHTML = '<div class="empty">no cases match</div>';
+    return;
+  }
+  grid.innerHTML = rows.map(r => renderRow(r, aName, bName)).join('');
+}
+
+function renderRow({ cid, a, b, dh }, aName, bName) {
+  const klass = Math.abs(dh) >= 4 ? 'row changed' : 'row';
+  const dhKlass = classifyDh(dh);
+  const dhText = dh === 0 ? '±0' : (dh > 0 ? `+${dh}` : `${dh}`);
+  const aFonts = a && a.fonts ? fontsHistToString(a.fonts) : '—';
+  const bFonts = b && b.fonts ? fontsHistToString(b.fonts) : '—';
+  const tpl = (a && a.template) || (b && b.template) || '';
+  const tid = (a && a.test_id) || (b && b.test_id) || '';
+  return `
+    <div class="${klass}">
+      <div class="row-head">
+        <span class="case-id">${cid}</span>
+        <span class="pill tpl">${tpl}</span>
+        <span class="pill">${tid}</span>
+        <span class="badge ${dhKlass}">Δh ${dhText}px</span>
+        <span class="row-meta">${a ? `left ${a.w}×${a.h}` : 'left missing'} · ${b ? `right ${b.w}×${b.h}` : 'right missing'}</span>
+      </div>
+      <div class="pair">
+        ${renderPanel(a, aName, aFonts)}
+        ${renderPanel(b, bName, bFonts)}
+      </div>
+      ${a && a.title ? `<details><summary>show title text / description</summary>
+        <pre>title: ${escapeHtml(a.title)}\\ndescription: ${escapeHtml(a.description||'')}</pre></details>` : ''}
+    </div>`;
+}
+
+function renderPanel(rec, runName, fontsStr) {
+  if (!rec) return `<div class="panel missing">missing in ${runName}</div>`;
+  if (!rec.ok) return `<div class="panel missing">failed: ${escapeHtml(rec.reason||'')}</div>`;
+  if (!rec.png) return `<div class="panel missing">no png for ${runName}</div>`;
+  return `<div class="panel">
+    <div class="head"><span>${runName}</span><span class="fonts">${fontsStr}</span></div>
+    <img src="${rec.png}" alt="${rec.png}">
+  </div>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, ch => ({
+    '&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'
+  })[ch]);
+}
+
+function populateSelects() {
+  const names = Object.keys(RUNS);
+  const [defA, defB] = pickDefaults();
+  for (const id of ['runA', 'runB']) {
+    const sel = document.getElementById(id);
+    sel.innerHTML = names.map(n => `<option value="${n}">${n}</option>`).join('');
+    sel.value = id === 'runA' ? defA : defB;
+    sel.addEventListener('change', render);
+  }
+  document.getElementById('filter').addEventListener('input', render);
+  document.getElementById('sort').addEventListener('change', render);
+  document.getElementById('onlyChanged').addEventListener('change', render);
+}
+
+if (Object.keys(RUNS).length === 0) {
+  document.getElementById('grid').innerHTML =
+    '<div class="empty">no runs found. run <code>tests/title_styler_regression/run.py --run baseline</code> first.</div>';
+} else {
+  populateSelects();
+  render();
+}
+</script>
+</body>
+</html>
+"""
+
+
+def main():
+    runs = discover_runs()
+    if not runs:
+        print("no run found under tests/title_styler_regression/results/", file=sys.stderr)
+        print("first run:", file=sys.stderr)
+        print("  PYTHONPATH=. python tests/title_styler_regression/run.py --run baseline",
+              file=sys.stderr)
+    payload = json.dumps(runs, ensure_ascii=False)
+    html = HTML_TEMPLATE.replace("__RUNS_JSON__", payload)
+    with open(OUT_HTML, "w", encoding="utf-8") as f:
+        f.write(html)
+    print(f"wrote {OUT_HTML}")
+    if runs:
+        print("available runs:")
+        for name, r in runs.items():
+            print(f"  - {name}  ok={r['n_ok']} fail={r['n_fail']}")
+    print(f"\nopen in browser:  file://{OUT_HTML}")
+
+
+if __name__ == "__main__":
+    main()