Upload folder using huggingface_hub

commercial_fci_infographic_pipeline/__init__.py

@@ -0,0 +1,3 @@
+from .pipeline import PipelineConfig, run_baseline_batch, run_baseline_single, run_batch, run_single
+
+__all__ = ["PipelineConfig", "run_batch", "run_single", "run_baseline_batch", "run_baseline_single"]

commercial_fci_infographic_pipeline/run.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .pipeline import DEFAULT_INPUT_DIR, PipelineConfig, run_batch
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build foreground-conditioned infographic composites from chart PNG assets."
+    )
+    parser.add_argument(
+        "--input-dir",
+        type=Path,
+        default=DEFAULT_INPUT_DIR,
+        help="Directory containing chart PNGs or a manifest.jsonl with final_png/chart_png records.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=PipelineConfig.output_dir,
+        help="Directory for condition packages, candidates, final composites, and reports.",
+    )
+    parser.add_argument(
+        "--prompt",
+        default=PipelineConfig.user_prompt,
+        help="Target infographic scene prompt.",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Maximum number of chart assets to process.",
+    )
+    parser.add_argument(
+        "--template-filter",
+        action="append",
+        default=[],
+        help="Case-insensitive substring filter for template_key or asset_id. Can be passed multiple times.",
+    )
+    parser.add_argument(
+        "--sample-index",
+        action="append",
+        type=int,
+        default=[],
+        help="Only include this sample_index. Can be passed multiple times.",
+    )
+    parser.add_argument(
+        "--candidates",
+        type=int,
+        default=PipelineConfig.candidates_per_chart,
+        help="Number of prompt variants/candidates per chart.",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=PipelineConfig.workers,
+        help="Number of chart assets to process concurrently.",
+    )
+    parser.add_argument(
+        "--canvas-width",
+        type=int,
+        default=PipelineConfig.canvas_width,
+    )
+    parser.add_argument(
+        "--canvas-height",
+        type=int,
+        default=PipelineConfig.canvas_height,
+    )
+    parser.add_argument(
+        "--max-chart-width-ratio",
+        type=float,
+        default=PipelineConfig.max_chart_width_ratio,
+        help="Maximum chart width as a fraction of canvas width.",
+    )
+    parser.add_argument(
+        "--max-chart-height-ratio",
+        type=float,
+        default=PipelineConfig.max_chart_height_ratio,
+        help="Maximum chart height as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--foreground-top-ratio",
+        type=float,
+        default=PipelineConfig.foreground_top_ratio,
+        help="Preferred chart top offset as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--foreground-bottom-margin-ratio",
+        type=float,
+        default=PipelineConfig.foreground_bottom_margin_ratio,
+        help="Minimum chart bottom margin as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--protected-layout-margin",
+        type=int,
+        default=PipelineConfig.protected_layout_margin_px,
+        help="Extra no-overlap margin around the fixed foreground bbox.",
+    )
+    parser.add_argument(
+        "--alpha-mode",
+        choices=["opaque", "rgba", "background-key", "auto"],
+        default=PipelineConfig.foreground_alpha_mode,
+        help="How to derive foreground alpha from chart images.",
+    )
+    parser.add_argument(
+        "--prefer-svg",
+        action="store_true",
+        help=(
+            "Render from SVG when an SVG is available, even if a PNG exists. "
+            "Transparent SVG renders preserve alpha automatically when --alpha-mode is left as opaque."
+        ),
+    )
+    parser.add_argument(
+        "--keep-best-only",
+        action="store_true",
+        help="Remove non-best candidate directories after reranking.",
+    )
+    parser.add_argument(
+        "--agent-model",
+        default=PipelineConfig.agent_model,
+        help="OpenAI text/vision model for analyzer, planner, prompt ensemble, and critic agents.",
+    )
+    parser.add_argument(
+        "--agent-reasoning-effort",
+        default=PipelineConfig.agent_reasoning_effort,
+        help="Reasoning effort passed to GPT-backed agents when supported.",
+    )
+    parser.add_argument(
+        "--generator",
+        choices=["gpt-image-2", "openai"],
+        default=PipelineConfig.generator,
+        help="Candidate generator adapter.",
+    )
+    parser.add_argument(
+        "--openai-model",
+        default=PipelineConfig.openai_model,
+        help="OpenAI image model name used by the GPT-Image adapter.",
+    )
+    parser.add_argument(
+        "--openai-quality",
+        default=PipelineConfig.openai_quality,
+        help="OpenAI image quality parameter.",
+    )
+    parser.add_argument(
+        "--openai-api-key-env",
+        default=PipelineConfig.openai_api_key_env,
+        help="Environment variable that contains the OpenAI API key.",
+    )
+    parser.add_argument(
+        "--openai-timeout",
+        type=float,
+        default=PipelineConfig.openai_timeout_seconds,
+        help="OpenAI request timeout in seconds.",
+    )
+    parser.add_argument(
+        "--openai-max-retries",
+        type=int,
+        default=PipelineConfig.openai_max_retries,
+        help="OpenAI SDK retry count for transient failures.",
+    )
+    parser.add_argument(
+        "--openai-base-url",
+        default=PipelineConfig.openai_base_url,
+        help="Optional OpenAI-compatible base URL or gateway endpoint.",
+    )
+    parser.add_argument("--experiment-id", default=PipelineConfig.experiment_id)
+    parser.add_argument("--variant-id", default=PipelineConfig.variant_id)
+    parser.add_argument(
+        "--disable-protected-sanitize",
+        action="store_true",
+        help="Ablation: do not clean the protected layout zone before restoring the chart.",
+    )
+    parser.add_argument(
+        "--disable-foreground-restore",
+        action="store_true",
+        help="Ablation: use the generated/sanitized candidate as final output without pasting back the original chart.",
+    )
+    parser.add_argument(
+        "--quality-eval",
+        action="store_true",
+        help="Run an additional GPT quality evaluator for every candidate.",
+    )
+    parser.add_argument(
+        "--quality-eval-model",
+        default=PipelineConfig.quality_eval_model,
+        help="Model for the additional quality evaluator. Defaults to --agent-model.",
+    )
+    parser.add_argument(
+        "--rank-by",
+        choices=[
+            "overall",
+            "gpt_quality_overall",
+            "chart_change_score",
+            "chart_faithfulness_score",
+            "infographic_quality_score",
+        ],
+        default=PipelineConfig.rank_by,
+        help="Candidate selection score. chart_change_score selects the lowest chart change.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    config = PipelineConfig(
+        input_dir=args.input_dir,
+        output_dir=args.output_dir,
+        user_prompt=args.prompt,
+        canvas_width=args.canvas_width,
+        canvas_height=args.canvas_height,
+        max_chart_width_ratio=args.max_chart_width_ratio,
+        max_chart_height_ratio=args.max_chart_height_ratio,
+        foreground_top_ratio=args.foreground_top_ratio,
+        foreground_bottom_margin_ratio=args.foreground_bottom_margin_ratio,
+        protected_layout_margin_px=args.protected_layout_margin,
+        foreground_alpha_mode=args.alpha_mode,
+        candidates_per_chart=args.candidates,
+        max_charts=args.limit,
+        workers=args.workers,
+        template_filters=tuple(args.template_filter),
+        sample_indices=tuple(args.sample_index),
+        prefer_svg_source=args.prefer_svg,
+        save_all_candidates=not args.keep_best_only,
+        agent_model=args.agent_model,
+        agent_reasoning_effort=args.agent_reasoning_effort,
+        generator=args.generator,
+        openai_model=args.openai_model,
+        openai_quality=args.openai_quality,
+        openai_api_key_env=args.openai_api_key_env,
+        openai_timeout_seconds=args.openai_timeout,
+        openai_max_retries=args.openai_max_retries,
+        openai_base_url=args.openai_base_url,
+        experiment_id=args.experiment_id,
+        variant_id=args.variant_id,
+        pipeline_mode="full",
+        sanitize_protected_zone=not args.disable_protected_sanitize,
+        restore_foreground_enabled=not args.disable_foreground_restore,
+        gpt_quality_eval=args.quality_eval,
+        quality_eval_model=args.quality_eval_model,
+        rank_by=args.rank_by,
+    )
+    reports = run_batch(config)
+    print(f"Completed {len(reports)} chart assets. Batch report: {config.output_dir / 'batch_report.json'}")
+
+
+if __name__ == "__main__":
+    main()

commercial_fci_infographic_pipeline/run_baseline.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .pipeline import DEFAULT_INPUT_DIR, PipelineConfig, run_baseline_batch
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Baseline: send a transparent chart PNG directly to GPT-Image and restore the original chart."
+    )
+    parser.add_argument(
+        "--input-dir",
+        type=Path,
+        default=DEFAULT_INPUT_DIR,
+        help="Directory containing chart PNGs/SVGs or a manifest.jsonl.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("output/commercial_fci_baseline_outputs"),
+        help="Directory for baseline transparent inputs, candidates, final composites, and reports.",
+    )
+    parser.add_argument(
+        "--prompt",
+        default=PipelineConfig.user_prompt,
+        help="Target infographic style prompt.",
+    )
+    parser.add_argument("--limit", type=int, default=None, help="Maximum number of chart assets to process.")
+    parser.add_argument(
+        "--template-filter",
+        action="append",
+        default=[],
+        help="Case-insensitive substring filter for template_key or asset_id. Can be passed multiple times.",
+    )
+    parser.add_argument(
+        "--sample-index",
+        action="append",
+        type=int,
+        default=[],
+        help="Only include this sample_index. Can be passed multiple times.",
+    )
+    parser.add_argument(
+        "--candidates",
+        type=int,
+        default=1,
+        help="Number of direct GPT-Image candidates per chart.",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        help="Number of chart assets to process concurrently.",
+    )
+    parser.add_argument("--canvas-width", type=int, default=PipelineConfig.canvas_width)
+    parser.add_argument("--canvas-height", type=int, default=PipelineConfig.canvas_height)
+    parser.add_argument(
+        "--max-chart-width-ratio",
+        type=float,
+        default=PipelineConfig.max_chart_width_ratio,
+        help="Maximum chart width as a fraction of canvas width.",
+    )
+    parser.add_argument(
+        "--max-chart-height-ratio",
+        type=float,
+        default=PipelineConfig.max_chart_height_ratio,
+        help="Maximum chart height as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--foreground-top-ratio",
+        type=float,
+        default=PipelineConfig.foreground_top_ratio,
+        help="Preferred chart top offset as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--foreground-bottom-margin-ratio",
+        type=float,
+        default=PipelineConfig.foreground_bottom_margin_ratio,
+        help="Minimum chart bottom margin as a fraction of canvas height.",
+    )
+    parser.add_argument(
+        "--protected-layout-margin",
+        type=int,
+        default=PipelineConfig.protected_layout_margin_px,
+        help="No-overlap margin around the fixed chart bbox described to GPT-Image.",
+    )
+    parser.add_argument(
+        "--alpha-mode",
+        choices=["opaque", "rgba", "background-key", "auto"],
+        default=PipelineConfig.foreground_alpha_mode,
+        help="How to derive foreground alpha from chart images.",
+    )
+    parser.add_argument(
+        "--prefer-svg",
+        action="store_true",
+        help="Render from SVG when an SVG is available, even if a PNG exists.",
+    )
+    parser.add_argument(
+        "--keep-best-only",
+        action="store_true",
+        help="Remove non-best candidate directories after deterministic foreground scoring.",
+    )
+    parser.add_argument(
+        "--generator",
+        choices=["gpt-image-2", "openai"],
+        default=PipelineConfig.generator,
+        help="Candidate generator adapter.",
+    )
+    parser.add_argument(
+        "--openai-model",
+        default=PipelineConfig.openai_model,
+        help="OpenAI image model name used by the GPT-Image adapter.",
+    )
+    parser.add_argument(
+        "--openai-quality",
+        default=PipelineConfig.openai_quality,
+        help="OpenAI image quality parameter.",
+    )
+    parser.add_argument(
+        "--openai-api-key-env",
+        default=PipelineConfig.openai_api_key_env,
+        help="Environment variable that contains the OpenAI API key.",
+    )
+    parser.add_argument(
+        "--openai-timeout",
+        type=float,
+        default=PipelineConfig.openai_timeout_seconds,
+        help="OpenAI request timeout in seconds.",
+    )
+    parser.add_argument(
+        "--openai-max-retries",
+        type=int,
+        default=PipelineConfig.openai_max_retries,
+        help="OpenAI SDK retry count for transient failures.",
+    )
+    parser.add_argument(
+        "--openai-base-url",
+        default=PipelineConfig.openai_base_url,
+        help="Optional OpenAI-compatible base URL or gateway endpoint.",
+    )
+    parser.add_argument("--experiment-id", default=PipelineConfig.experiment_id)
+    parser.add_argument("--variant-id", default=PipelineConfig.variant_id)
+    parser.add_argument(
+        "--quality-eval",
+        action="store_true",
+        help="Run an additional GPT quality evaluator for every baseline candidate.",
+    )
+    parser.add_argument(
+        "--quality-eval-model",
+        default=PipelineConfig.quality_eval_model,
+        help="Model for the additional quality evaluator. Defaults to PipelineConfig.agent_model.",
+    )
+    parser.add_argument(
+        "--rank-by",
+        choices=[
+            "overall",
+            "gpt_quality_overall",
+            "chart_change_score",
+            "chart_faithfulness_score",
+            "infographic_quality_score",
+        ],
+        default=PipelineConfig.rank_by,
+        help="Candidate selection score. chart_change_score selects the lowest chart change.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    config = PipelineConfig(
+        input_dir=args.input_dir,
+        output_dir=args.output_dir,
+        user_prompt=args.prompt,
+        canvas_width=args.canvas_width,
+        canvas_height=args.canvas_height,
+        max_chart_width_ratio=args.max_chart_width_ratio,
+        max_chart_height_ratio=args.max_chart_height_ratio,
+        foreground_top_ratio=args.foreground_top_ratio,
+        foreground_bottom_margin_ratio=args.foreground_bottom_margin_ratio,
+        protected_layout_margin_px=args.protected_layout_margin,
+        foreground_alpha_mode=args.alpha_mode,
+        candidates_per_chart=args.candidates,
+        max_charts=args.limit,
+        workers=args.workers,
+        template_filters=tuple(args.template_filter),
+        sample_indices=tuple(args.sample_index),
+        prefer_svg_source=args.prefer_svg,
+        save_all_candidates=not args.keep_best_only,
+        generator=args.generator,
+        openai_model=args.openai_model,
+        openai_quality=args.openai_quality,
+        openai_api_key_env=args.openai_api_key_env,
+        openai_timeout_seconds=args.openai_timeout,
+        openai_max_retries=args.openai_max_retries,
+        openai_base_url=args.openai_base_url,
+        experiment_id=args.experiment_id,
+        variant_id=args.variant_id,
+        pipeline_mode="baseline_transparent_chart_direct",
+        gpt_quality_eval=args.quality_eval,
+        quality_eval_model=args.quality_eval_model,
+        rank_by=args.rank_by,
+    )
+    reports = run_baseline_batch(config)
+    print(f"Completed {len(reports)} baseline chart assets. Batch report: {config.output_dir / 'batch_report.json'}")
+
+
+if __name__ == "__main__":
+    main()

commercial_fci_infographic_pipeline/run_experiments.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+import argparse
+import json
+import time
+import traceback
+from dataclasses import fields, replace
+from pathlib import Path
+from typing import Any
+
+from .pipeline import DEFAULT_INPUT_DIR, PipelineConfig, run_baseline_batch, run_batch, write_json
+
+
+PATH_FIELDS = {"input_dir", "output_dir"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run FCI infographic ablation variants and summarize deterministic/GPT quality metrics."
+    )
+    parser.add_argument("--plan", type=Path, help="Optional JSON experiment plan.")
+    parser.add_argument(
+        "--preset",
+        choices=["baseline_vs_full", "core", "full_only", "baseline_only"],
+        default="baseline_vs_full",
+        help="Built-in variant matrix used when --plan is not provided.",
+    )
+    parser.add_argument("--input-dir", type=Path, default=DEFAULT_INPUT_DIR)
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="Experiment root. Defaults to output/fci_infographic_experiments_<timestamp>.",
+    )
+    parser.add_argument("--prompt", default=PipelineConfig.user_prompt)
+    parser.add_argument("--limit", type=int, default=None)
+    parser.add_argument("--template-filter", action="append", default=[])
+    parser.add_argument("--sample-index", action="append", type=int, default=[])
+    parser.add_argument("--candidates", type=int, default=1)
+    parser.add_argument("--workers", type=int, default=1)
+    parser.add_argument("--prefer-svg", action="store_true")
+    parser.add_argument("--alpha-mode", choices=["opaque", "rgba", "background-key", "auto"], default=PipelineConfig.foreground_alpha_mode)
+    parser.add_argument("--agent-model", default=PipelineConfig.agent_model)
+    parser.add_argument("--agent-reasoning-effort", default="low")
+    parser.add_argument("--generator", choices=["gpt-image-2", "openai"], default=PipelineConfig.generator)
+    parser.add_argument("--openai-model", default=PipelineConfig.openai_model)
+    parser.add_argument("--openai-quality", default=PipelineConfig.openai_quality)
+    parser.add_argument("--openai-api-key-env", default=PipelineConfig.openai_api_key_env)
+    parser.add_argument("--openai-timeout", type=float, default=PipelineConfig.openai_timeout_seconds)
+    parser.add_argument("--openai-max-retries", type=int, default=PipelineConfig.openai_max_retries)
+    parser.add_argument("--openai-base-url", default=PipelineConfig.openai_base_url)
+    parser.add_argument(
+        "--no-quality-eval",
+        action="store_true",
+        help="Disable the additional GPT quality evaluator. Deterministic Change Score is still computed.",
+    )
+    parser.add_argument(
+        "--quality-eval-model",
+        default=PipelineConfig.quality_eval_model,
+        help="Model for quality evaluation. Defaults to --agent-model.",
+    )
+    parser.add_argument(
+        "--rank-by",
+        choices=[
+            "overall",
+            "gpt_quality_overall",
+            "chart_change_score",
+            "chart_faithfulness_score",
+            "infographic_quality_score",
+        ],
+        default=PipelineConfig.rank_by,
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    timestamp = time.strftime("%Y%m%d_%H%M%S")
+    experiment_root = args.output_dir or Path(f"output/fci_infographic_experiments_{timestamp}")
+    experiment_root.mkdir(parents=True, exist_ok=True)
+
+    plan = load_plan(args.plan) if args.plan else None
+    experiment_id = str((plan or {}).get("name") or experiment_root.name)
+    base_config = build_base_config(args, experiment_root, experiment_id)
+    if plan and isinstance(plan.get("shared"), dict):
+        base_config = apply_config_overrides(base_config, plan["shared"])
+    variants = plan.get("variants", []) if plan else preset_variants(args.preset)
+    if not variants:
+        raise ValueError("Experiment plan does not contain variants.")
+
+    results: list[dict[str, Any]] = []
+    for variant in variants:
+        variant_id = slug_variant_id(str(variant.get("id") or variant.get("pipeline") or f"variant_{len(results):02d}"))
+        pipeline = str(variant.get("pipeline") or "full")
+        overrides = variant.get("overrides") if isinstance(variant.get("overrides"), dict) else {}
+        config = apply_config_overrides(
+            replace(
+                base_config,
+                output_dir=experiment_root / variant_id,
+                variant_id=variant_id,
+                pipeline_mode=str(overrides.get("pipeline_mode") or pipeline),
+            ),
+            overrides,
+        )
+        started = time.time()
+        try:
+            if pipeline in {"baseline", "direct", "baseline_transparent_chart_direct"}:
+                config = replace(config, pipeline_mode="baseline_transparent_chart_direct")
+                reports = run_baseline_batch(config)
+            elif pipeline in {"full", "commercial_fci", "fci"}:
+                reports = run_batch(config)
+            else:
+                raise ValueError(f"Unknown experiment pipeline: {pipeline}")
+            results.append(
+                {
+                    "variant_id": variant_id,
+                    "pipeline": pipeline,
+                    "output_dir": str(config.output_dir),
+                    "elapsed_seconds": round(time.time() - started, 3),
+                    "completed_count": len(reports),
+                    "failed": False,
+                    "metrics": summarize_reports(reports),
+                    "reports": [report["export"]["report"] for report in reports],
+                }
+            )
+        except Exception as exc:
+            results.append(
+                {
+                    "variant_id": variant_id,
+                    "pipeline": pipeline,
+                    "output_dir": str(config.output_dir),
+                    "elapsed_seconds": round(time.time() - started, 3),
+                    "completed_count": 0,
+                    "failed": True,
+                    "error_type": exc.__class__.__name__,
+                    "message": str(exc),
+                    "traceback": traceback.format_exc(),
+                }
+            )
+        write_experiment_summary(experiment_root, experiment_id, base_config, results)
+
+    print(f"Experiment complete. Summary: {experiment_root / 'experiment_summary.json'}")
+
+
+def load_plan(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    if not isinstance(data, dict):
+        raise ValueError("Experiment plan must be a JSON object.")
+    return data
+
+
+def build_base_config(args: argparse.Namespace, experiment_root: Path, experiment_id: str) -> PipelineConfig:
+    return PipelineConfig(
+        input_dir=args.input_dir,
+        output_dir=experiment_root,
+        user_prompt=args.prompt,
+        foreground_alpha_mode=args.alpha_mode,
+        candidates_per_chart=args.candidates,
+        max_charts=args.limit,
+        workers=args.workers,
+        template_filters=tuple(args.template_filter),
+        sample_indices=tuple(args.sample_index),
+        prefer_svg_source=args.prefer_svg,
+        agent_model=args.agent_model,
+        agent_reasoning_effort=args.agent_reasoning_effort,
+        generator=args.generator,
+        openai_model=args.openai_model,
+        openai_quality=args.openai_quality,
+        openai_api_key_env=args.openai_api_key_env,
+        openai_timeout_seconds=args.openai_timeout,
+        openai_max_retries=args.openai_max_retries,
+        openai_base_url=args.openai_base_url,
+        experiment_id=experiment_id,
+        gpt_quality_eval=not args.no_quality_eval,
+        quality_eval_model=args.quality_eval_model,
+        rank_by=args.rank_by,
+    )
+
+
+def preset_variants(name: str) -> list[dict[str, Any]]:
+    if name == "baseline_only":
+        return [{"id": "baseline_direct", "pipeline": "baseline"}]
+    if name == "full_only":
+        return [{"id": "full", "pipeline": "full"}]
+    if name == "baseline_vs_full":
+        return [
+            {"id": "baseline_direct", "pipeline": "baseline"},
+            {"id": "full", "pipeline": "full"},
+        ]
+    return [
+        {"id": "baseline_direct", "pipeline": "baseline"},
+        {"id": "full", "pipeline": "full"},
+        {
+            "id": "full_no_sanitize",
+            "pipeline": "full",
+            "overrides": {"sanitize_protected_zone": False, "pipeline_mode": "full_no_sanitize"},
+        },
+        {
+            "id": "full_no_restore",
+            "pipeline": "full",
+            "overrides": {"restore_foreground_enabled": False, "pipeline_mode": "full_no_restore"},
+        },
+    ]
+
+
+def apply_config_overrides(config: PipelineConfig, overrides: dict[str, Any]) -> PipelineConfig:
+    known = {field.name for field in fields(PipelineConfig)}
+    updates: dict[str, Any] = {}
+    for key, value in overrides.items():
+        if key not in known:
+            raise ValueError(f"Unknown PipelineConfig override: {key}")
+        updates[key] = Path(value) if key in PATH_FIELDS and value is not None else value
+    return replace(config, **updates)
+
+
+def summarize_reports(reports: list[dict[str, Any]]) -> dict[str, Any]:
+    best_candidates = [report.get("best_candidate", {}) for report in reports]
+    rows = []
+    for report, candidate in zip(reports, best_candidates):
+        measurements = ((candidate.get("metadata") or {}).get("measurements") or {})
+        chart_faithfulness = ((candidate.get("metadata") or {}).get("chart_faithfulness") or {})
+        infographic_quality = ((candidate.get("metadata") or {}).get("infographic_quality") or {})
+        quality = ((candidate.get("metadata") or {}).get("quality_evaluation") or {}).get("scores") or {}
+        rows.append(
+            {
+                "task_id": report.get("task_id"),
+                "overall": (candidate.get("score") or {}).get("overall"),
+                "chart_faithfulness_score": (candidate.get("score") or {}).get("chart_faithfulness_score")
+                or chart_faithfulness.get("score")
+                or measurements.get("chart_faithfulness_score"),
+                "infographic_quality_score": (candidate.get("score") or {}).get("infographic_quality_score")
+                or infographic_quality.get("score"),
+                "gpt_quality_overall": (candidate.get("score") or {}).get("gpt_quality_overall")
+                or quality.get("overall_quality"),
+                "chart_change_score": measurements.get("chart_change_score"),
+                "chart_pixel_change_score": measurements.get("chart_pixel_change_score"),
+                "chart_deformation_score": measurements.get("chart_deformation_score"),
+                "chart_displacement_score": measurements.get("chart_displacement_score"),
+                "chart_alignment_reliable": measurements.get("chart_alignment_reliable"),
+            }
+        )
+    return {
+        "count": len(rows),
+        "averages": {
+            "overall": average(row["overall"] for row in rows),
+            "chart_faithfulness_score": average(row["chart_faithfulness_score"] for row in rows),
+            "infographic_quality_score": average(row["infographic_quality_score"] for row in rows),
+            "gpt_quality_overall": average(row["gpt_quality_overall"] for row in rows),
+            "chart_change_score": average(row["chart_change_score"] for row in rows),
+            "chart_pixel_change_score": average(row["chart_pixel_change_score"] for row in rows),
+            "chart_deformation_score": average(row["chart_deformation_score"] for row in rows),
+            "chart_displacement_score": average(row["chart_displacement_score"] for row in rows),
+        },
+        "items": rows,
+    }
+
+
+def write_experiment_summary(
+    experiment_root: Path,
+    experiment_id: str,
+    base_config: PipelineConfig,
+    results: list[dict[str, Any]],
+) -> None:
+    write_json(
+        experiment_root / "experiment_summary.json",
+        {
+            "experiment_id": experiment_id,
+            "output_dir": str(experiment_root),
+            "input_dir": str(base_config.input_dir),
+            "quality_eval_model": base_config.quality_eval_model or base_config.agent_model,
+            "gpt_quality_eval": base_config.gpt_quality_eval,
+            "rank_by": base_config.rank_by,
+            "variants": results,
+        },
+    )
+
+
+def average(values: Any) -> float | None:
+    numeric = [float(value) for value in values if isinstance(value, (int, float))]
+    if not numeric:
+        return None
+    return round(sum(numeric) / len(numeric), 6)
+
+
+def slug_variant_id(value: str) -> str:
+    cleaned = "".join(ch.lower() if ch.isalnum() else "_" for ch in value).strip("_")
+    while "__" in cleaned:
+        cleaned = cleaned.replace("__", "_")
+    return cleaned or "variant"
+
+
+if __name__ == "__main__":
+    main()

commercial_fci_infographic_pipeline/viewer.py

@@ -0,0 +1,1621 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import html
+import json
+import mimetypes
+import re
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, unquote, urlparse
+
+
+WORKSPACE_ROOT = Path(__file__).resolve().parents[1]
+
+DEFAULT_OUTPUT_ROOTS: list[Path] = []
+
+DEFAULT_SCAN_ROOTS = [
+    WORKSPACE_ROOT / "output",
+    WORKSPACE_ROOT / "shared_output/personal/liduan",
+]
+_INDEX_HTML_CACHE: tuple[int, int, str, str] | None = None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Serve a small browser UI for FCI infographic outputs.")
+    parser.add_argument("--host", default="0.0.0.0", help="Bind host. Use 0.0.0.0 on a server.")
+    parser.add_argument("--port", type=int, default=8765, help="Bind port.")
+    parser.add_argument(
+        "--output-root",
+        action="append",
+        type=Path,
+        help="Pipeline output root. Can be passed multiple times. These are re-scanned on every refresh.",
+    )
+    parser.add_argument(
+        "--scan-root",
+        action="append",
+        type=Path,
+        help="Parent directory to scan for FCI infographic output roots. Defaults to ./output and shared_output/personal/liduan.",
+    )
+    parser.add_argument(
+        "--no-auto-discover",
+        action="store_true",
+        help="Only use explicit --output-root values and built-in defaults.",
+    )
+    parser.add_argument(
+        "--show-all-roots",
+        action="store_true",
+        help="Show every discovered experiment root. By default the viewer shows only the newest discovered root.",
+    )
+    parser.add_argument(
+        "--show-legacy",
+        action="store_true",
+        help="Include legacy non-experiment output roots such as old batch_report.json runs.",
+    )
+    return parser.parse_args()
+
+
+def safe_resolve(path: Path) -> Path:
+    return path.expanduser().resolve()
+
+
+class ViewerState:
+    def __init__(
+        self,
+        output_roots: list[Path],
+        scan_roots: list[Path] | None = None,
+        *,
+        auto_discover: bool = True,
+        show_all_roots: bool = False,
+        include_legacy: bool = False,
+    ) -> None:
+        roots = DEFAULT_OUTPUT_ROOTS + output_roots
+        self.explicit_output_roots = [safe_resolve(root) for root in roots]
+        self.scan_roots = [safe_resolve(root) for root in (scan_roots or DEFAULT_SCAN_ROOTS)]
+        self.auto_discover = auto_discover
+        self.show_all_roots = show_all_roots
+        self.include_legacy = include_legacy
+        self._roots_cache: list[Path] = []
+        self._roots_cache_until = 0.0
+
+    def output_roots(self, *, force: bool = False) -> list[Path]:
+        now = time.time()
+        if not force and now < self._roots_cache_until:
+            return list(self._roots_cache)
+
+        roots: list[Path] = []
+        seen: set[Path] = set()
+
+        def add(root: Path) -> None:
+            resolved = safe_resolve(root)
+            if resolved in seen or not resolved.is_dir():
+                return
+            seen.add(resolved)
+            roots.append(resolved)
+
+        for root in self.explicit_output_roots:
+            add(root)
+        if self.auto_discover:
+            discovered = discover_output_roots(self.scan_roots, include_legacy=self.include_legacy)
+            if not self.show_all_roots:
+                discovered = discovered[:1]
+            for root in discovered:
+                add(root)
+        self._roots_cache = roots
+        self._roots_cache_until = now + 15.0
+        return roots
+
+    def reports(self, roots: list[Path] | None = None) -> list[dict]:
+        items: list[dict] = []
+        for root in roots or self.output_roots():
+            try:
+                children = report_task_dirs(root)
+            except OSError:
+                continue
+            for task_dir in children:
+                report = read_json_file(task_dir / "report.json") or {}
+                status = read_json_file(task_dir / "task_status.json") or {}
+                error = read_json_file(task_dir / "task_error.json") or None
+                if not report and not status:
+                    continue
+                items.append(task_item(root, task_dir, report, status, error))
+        items.sort(
+            key=lambda item: (int(item.get("updated_mtime_ns") or 0), item["task_dir"]),
+            reverse=True,
+        )
+        return items
+
+    def resolve_asset(self, raw_path: str) -> Path | None:
+        if not raw_path:
+            return None
+        candidate = safe_resolve(Path(unquote(raw_path)))
+        for root in self.output_roots():
+            try:
+                candidate.relative_to(root)
+            except ValueError:
+                continue
+            if candidate.is_file():
+                return candidate
+        return None
+
+
+def read_json_file(path: Path) -> dict | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def report_task_dirs(root: Path) -> list[Path]:
+    if (root / "experiment_summary.json").is_file():
+        task_dirs: list[Path] = []
+        for variant_dir in sorted((path for path in root.iterdir() if path.is_dir()), reverse=True):
+            task_dirs.extend(path for path in variant_dir.iterdir() if path.is_dir())
+        return task_dirs
+    return [path for path in root.iterdir() if path.is_dir()]
+
+
+def task_item(root: Path, task_dir: Path, report: dict, status: dict, error: dict | None) -> dict:
+    runtime = report.get("runtime", {})
+    input_info = report.get("input", {})
+    stages = collect_stages(task_dir, report)
+    updated_mtime_ns = task_mtime_ns(task_dir, stages)
+    return {
+        "id": str(task_dir),
+        "version": task_version(stages),
+        "updated_mtime_ns": updated_mtime_ns,
+        "root": str(root),
+        "task_dir": str(task_dir),
+        "task_id": report.get("task_id") or status.get("task_id") or task_dir.name,
+        "state": status.get("state") or ("completed" if report else "unknown"),
+        "stage": status.get("stage"),
+        "error": error or status.get("error"),
+        "pipeline_mode": runtime.get("pipeline_mode"),
+        "experiment_id": runtime.get("experiment_id"),
+        "variant_id": runtime.get("variant_id"),
+        "agent_mode": runtime.get("agent_mode"),
+        "agent_model": runtime.get("agent_model"),
+        "generator": runtime.get("generator_mode"),
+        "source_kind": input_info.get("source_kind"),
+        "effective_alpha_mode": input_info.get("effective_alpha_mode"),
+        "elapsed_seconds": runtime.get("elapsed_seconds") or status.get("elapsed_seconds"),
+        "bbox": input_info.get("foreground_bbox"),
+        "best": summarize_candidate(report.get("best_candidate", {})),
+        "candidates": [
+            summarize_candidate(candidate)
+            for candidate in report.get("all_candidates", [])
+        ],
+        "images": collect_images(task_dir, report),
+        "stages": stages,
+    }
+
+
+def task_mtime_ns(task_dir: Path, stages: list[dict]) -> int:
+    latest = path_mtime_ns(task_dir)
+    for filename in ("task_status.json", "report.json", "task_error.json", "final_composite.png"):
+        latest = max(latest, path_mtime_ns(task_dir / filename))
+    for stage in stages:
+        for file in stage.get("files", []):
+            latest = max(latest, int(file.get("mtime_ns") or 0))
+    return latest
+
+
+def discover_output_roots(scan_roots: list[Path], max_depth: int = 3, *, include_legacy: bool = False) -> list[Path]:
+    roots: list[Path] = []
+    seen: set[Path] = set()
+    for scan_root in scan_roots:
+        root = safe_resolve(scan_root)
+        if not root.is_dir():
+            continue
+        for candidate in iter_likely_output_dirs(root, max_depth=max_depth):
+            if is_under_seen_root(candidate, seen) or not looks_like_output_root(candidate, include_legacy=include_legacy):
+                continue
+            seen.add(candidate)
+            roots.append(candidate)
+    roots.sort(key=lambda path: (output_root_mtime_ns(path), str(path)), reverse=True)
+    return roots
+
+
+def is_under_seen_root(path: Path, seen: set[Path]) -> bool:
+    for root in seen:
+        try:
+            path.relative_to(root)
+        except ValueError:
+            continue
+        return True
+    return False
+
+
+def path_mtime_ns(path: Path) -> int:
+    try:
+        return path.stat().st_mtime_ns
+    except OSError:
+        return 0
+
+
+def output_root_mtime_ns(path: Path) -> int:
+    latest = path_mtime_ns(path)
+    for filename in (
+        "batch_report.json",
+        "experiment_summary.json",
+        "summary.json",
+        "manifest.jsonl",
+        "comparison_summary.json",
+    ):
+        latest = max(latest, path_mtime_ns(path / filename))
+    try:
+        children = [child for child in path.iterdir() if child.is_dir()]
+    except OSError:
+        return latest
+    for child in children:
+        latest = max(
+            latest,
+            path_mtime_ns(child),
+            path_mtime_ns(child / "task_status.json"),
+            path_mtime_ns(child / "report.json"),
+            path_mtime_ns(child / "final_composite.png"),
+        )
+    return latest
+
+
+def iter_likely_output_dirs(root: Path, max_depth: int) -> list[Path]:
+    if root == Path("/tmp").resolve():
+        candidates = [root]
+        try:
+            children = list(root.iterdir())
+        except OSError:
+            return candidates
+        for child in children:
+            if child.name.startswith(".") or child.is_symlink():
+                continue
+            try:
+                is_candidate = child.is_dir() and (
+                    child.name.startswith("commercial_fci") or (child / "batch_report.json").is_file()
+                )
+            except OSError:
+                continue
+            if is_candidate:
+                candidates.append(child)
+        return candidates
+    return iter_dirs(root, max_depth=max_depth)
+
+
+def iter_dirs(root: Path, max_depth: int) -> list[Path]:
+    dirs: list[Path] = []
+    stack: list[tuple[Path, int]] = [(root, 0)]
+    while stack:
+        current, depth = stack.pop()
+        dirs.append(current)
+        if depth >= max_depth:
+            continue
+        try:
+            children = list(current.iterdir())
+        except OSError:
+            continue
+        for child in children:
+            if child.name.startswith(".") or child.is_symlink():
+                continue
+            try:
+                is_dir = child.is_dir()
+            except OSError:
+                continue
+            if is_dir:
+                stack.append((child, depth + 1))
+    return dirs
+
+
+def looks_like_output_root(path: Path, *, include_legacy: bool = False) -> bool:
+    if (path / "experiment_summary.json").is_file():
+        return True
+    if not include_legacy:
+        return False
+    if (path / "batch_report.json").is_file() and any(path.glob("*/report.json")):
+        return True
+    if path.name.startswith("commercial_fci") and any(path.glob("*/report.json")):
+        return True
+    return False
+
+
+def summarize_candidate(candidate: dict) -> dict:
+    return {
+        "candidate_id": candidate.get("candidate_id"),
+        "variant_id": candidate.get("variant_id"),
+        "overall": candidate.get("score", {}).get("overall"),
+        "score": candidate.get("score", {}),
+        "failure_tags": candidate.get("failure_tags", []),
+        "raw_path": str(candidate.get("raw_path", "")),
+        "final_path": str(candidate.get("final_path", "")),
+        "metadata": candidate.get("metadata", {}),
+    }
+
+
+def collect_images(task_dir: Path, report: dict) -> dict:
+    export = report.get("export", {})
+    masks = report.get("masks", {})
+    paths = {
+        "final": export.get("final_composite"),
+        "background": export.get("background_candidate"),
+        "foreground": export.get("foreground"),
+        "alpha": export.get("alpha"),
+        "condition": str(task_dir / "condition_canvas.png"),
+        "foreground_on_canvas": str(task_dir / "foreground_on_canvas.png"),
+        "layout_guide": str(task_dir / masks["layout_guide"]) if masks.get("layout_guide") else "",
+        "protected_layout_zone": str(task_dir / masks["protected_layout_zone"]) if masks.get("protected_layout_zone") else "",
+        "clearance_zone": str(task_dir / masks["clearance_zone"]) if masks.get("clearance_zone") else "",
+    }
+    return {key: value for key, value in paths.items() if value and Path(value).is_file()}
+
+
+def collect_stages(task_dir: Path, report: dict) -> list[dict]:
+    stages: list[dict] = []
+
+    def add(label: str, files: list[tuple[str, Path]]) -> None:
+        entries = [
+            entry
+            for file_label, path in files
+            if (entry := file_entry(file_label, path)) is not None
+        ]
+        if entries:
+            stages.append({"label": label, "files": entries})
+
+    add(
+        "01 Source & Condition",
+        [
+            ("Rendered SVG", task_dir / "rendered_from_svg.png"),
+            ("Foreground RGBA", task_dir / "foreground_rgba.png"),
+            ("Foreground On Canvas", task_dir / "foreground_on_canvas.png"),
+            ("Foreground Alpha", task_dir / "foreground_alpha.png"),
+            ("Baseline Transparent Chart", task_dir / "baseline_transparent_chart.png"),
+            ("Condition Canvas", task_dir / "condition_canvas.png"),
+            ("Task Status", task_dir / "task_status.json"),
+        ],
+    )
+    add(
+        "02 Masks & Layout",
+        [
+            ("Alpha Core", task_dir / "masks/alpha_core.png"),
+            ("Alpha Soft", task_dir / "masks/alpha_soft.png"),
+            ("Boundary Ring", task_dir / "masks/boundary_ring.png"),
+            ("Chart Protect Mask", task_dir / "masks/chart_protect.png"),
+            ("Background Edit Mask", task_dir / "masks/background_edit.png"),
+            ("Contact Region", task_dir / "masks/contact_region.png"),
+            ("Protected Layout Zone", task_dir / "masks/protected_layout_zone.png"),
+            ("Clearance Zone", task_dir / "masks/clearance_zone.png"),
+            ("Layout Guide", task_dir / "masks/layout_guide.png"),
+        ],
+    )
+    add(
+        "03 Foreground Analyzer",
+        [
+            ("Request", task_dir / "foreground_analyzer_request.json"),
+            ("Response", task_dir / "foreground_analyzer_response.json"),
+            ("Condition Canvas", task_dir / "condition_canvas.png"),
+            ("Layout Guide", task_dir / "masks/layout_guide.png"),
+        ],
+    )
+    add(
+        "04 Scene Planner",
+        [
+            ("Request", task_dir / "scene_planner_request.json"),
+            ("Response", task_dir / "scene_planner_response.json"),
+            ("Layout Guide", task_dir / "masks/layout_guide.png"),
+        ],
+    )
+    add(
+        "05 Prompt Ensemble",
+        [
+            ("Request", task_dir / "prompt_ensemble_request.json"),
+            ("Response", task_dir / "prompt_ensemble_response.json"),
+        ],
+    )
+    candidates_dir = task_dir / "candidates"
+    if candidates_dir.exists():
+        for candidate_dir in sorted(path for path in candidates_dir.iterdir() if path.is_dir()):
+            add(
+                f"06 Candidate {candidate_dir.name}",
+                [
+                    ("Generation Request", candidate_dir / "generation_request.json"),
+                    ("OpenAI Edit Mask (transparent=edit)", candidate_dir / "openai_edit_mask.png"),
+                    ("Raw Candidate", candidate_dir / "raw_candidate.png"),
+                    ("Background For Restoration", candidate_dir / "background_for_restoration.png"),
+                    ("Restored Final", candidate_dir / "final_composite.png"),
+                    ("Aligned Original Chart Restored", candidate_dir / "restored_chart_composite.png"),
+                    ("Aligned Highlight Difference", candidate_dir / "highlight_difference.png"),
+                    ("Aligned Chart Difference Mask", candidate_dir / "chart_difference_mask.png"),
+                    ("Critic Request", candidate_dir / "critic_reranker_request.json"),
+                    ("Critic Response", candidate_dir / "critic_reranker_response.json"),
+                    ("Quality Eval Request", candidate_dir / "quality_evaluator_request.json"),
+                    ("Quality Eval Response", candidate_dir / "quality_evaluator_response.json"),
+                    ("Generation Error", candidate_dir / "generation_error.json"),
+                ],
+            )
+    export = report.get("export", {})
+    add(
+        "07 Final Export",
+        [
+            ("Final Composite", Path(export.get("final_composite") or task_dir / "final_composite.png")),
+            ("Background Candidate", Path(export.get("background_candidate") or task_dir / "background_candidate.png")),
+            ("Aligned Original Chart Restored", Path(export.get("restored_chart_composite") or task_dir / "restored_chart_composite.png")),
+            ("Aligned Highlight Difference", Path(export.get("highlight_difference") or task_dir / "highlight_difference.png")),
+            ("Aligned Chart Difference Mask", Path(export.get("chart_difference_mask") or task_dir / "chart_difference_mask.png")),
+            ("Report", task_dir / "report.json"),
+            ("Task Error", task_dir / "task_error.json"),
+        ],
+    )
+    return stages
+
+
+def file_entry(label: str, path: Path) -> dict | None:
+    try:
+        stat = path.stat()
+    except OSError:
+        return None
+    if not path.is_file():
+        return None
+    suffix = path.suffix.lower()
+    if suffix in {".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"}:
+        file_type = "image"
+    elif suffix == ".json":
+        file_type = "json"
+    else:
+        file_type = "file"
+    return {
+        "label": label,
+        "path": str(path),
+        "type": file_type,
+        "size": stat.st_size,
+        "mtime": stat.st_mtime,
+        "mtime_ns": stat.st_mtime_ns,
+        "version": f"{stat.st_mtime_ns}-{stat.st_size}",
+    }
+
+
+def task_version(stages: list[dict]) -> str:
+    latest_mtime_ns = 0
+    total_size = 0
+    file_count = 0
+    for stage in stages:
+        for file in stage.get("files", []):
+            latest_mtime_ns = max(latest_mtime_ns, int(file.get("mtime_ns") or 0))
+            total_size += int(file.get("size") or 0)
+            file_count += 1
+    return f"{latest_mtime_ns}-{file_count}-{total_size}"
+
+
+def current_index_html() -> str:
+    global _INDEX_HTML_CACHE
+    source_path = Path(__file__)
+    try:
+        stat = source_path.stat()
+        if _INDEX_HTML_CACHE and _INDEX_HTML_CACHE[:2] == (stat.st_mtime_ns, stat.st_size):
+            return _INDEX_HTML_CACHE[2]
+        source = source_path.read_text(encoding="utf-8")
+        match = re.search(r'\nINDEX_HTML\s*=\s*r"""(.*?)"""\n\n\ndef main\(', source, re.DOTALL)
+        if not match:
+            raise ValueError("INDEX_HTML block not found")
+        html_body = match.group(1)
+        version = hashlib.sha256(html_body.encode("utf-8")).hexdigest()[:16]
+        _INDEX_HTML_CACHE = (stat.st_mtime_ns, stat.st_size, html_body, version)
+        return html_body
+    except Exception:
+        if _INDEX_HTML_CACHE:
+            return _INDEX_HTML_CACHE[2]
+        return INDEX_HTML
+
+
+def current_index_version() -> str:
+    current_index_html()
+    if _INDEX_HTML_CACHE:
+        return _INDEX_HTML_CACHE[3]
+    return hashlib.sha256(INDEX_HTML.encode("utf-8")).hexdigest()[:16]
+
+
+class ViewerHandler(BaseHTTPRequestHandler):
+    state: ViewerState
+
+    def log_message(self, format: str, *args: object) -> None:
+        print(f"[viewer] {self.address_string()} - {format % args}")
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            self.send_html(current_index_html())
+            return
+        if parsed.path == "/api/viewer-version":
+            self.send_json({"version": current_index_version()})
+            return
+        if parsed.path == "/api/reports":
+            roots = self.state.output_roots(force=True)
+            self.send_json(
+                {
+                    "roots": [str(root) for root in roots],
+                    "scan_roots": [str(root) for root in self.state.scan_roots],
+                    "auto_discover": self.state.auto_discover,
+                    "show_all_roots": self.state.show_all_roots,
+                    "include_legacy": self.state.include_legacy,
+                    "reports": self.state.reports(roots),
+                }
+            )
+            return
+        if parsed.path == "/asset":
+            params = parse_qs(parsed.query)
+            asset_path = params.get("path", [""])[0]
+            resolved = self.state.resolve_asset(asset_path)
+            if resolved is None:
+                self.send_error(404, "asset not found or outside output roots")
+                return
+            self.send_file(resolved)
+            return
+        self.send_error(404)
+
+    def send_json(self, payload: dict) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def send_html(self, body: str) -> None:
+        encoded = body.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def send_file(self, path: Path) -> None:
+        stat = path.stat()
+        etag = f'"{stat.st_mtime_ns:x}-{stat.st_size:x}"'
+        if self.headers.get("If-None-Match") == etag:
+            self.send_response(304)
+            self.send_header("ETag", etag)
+            self.send_header("Cache-Control", "public, max-age=31536000, immutable")
+            self.end_headers()
+            return
+        body = path.read_bytes()
+        mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+        self.send_response(200)
+        self.send_header("Content-Type", mime)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("ETag", etag)
+        self.send_header("Last-Modified", self.date_time_string(stat.st_mtime))
+        self.send_header("Cache-Control", "public, max-age=31536000, immutable")
+        self.end_headers()
+        self.wfile.write(body)
+
+
+INDEX_HTML = r"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>FCI Infographic Viewer</title>
+  <style>
+    :root {
+      color-scheme: light;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #eef2f7;
+      color: #132033;
+    }
+    body { margin: 0; }
+    header {
+      height: 64px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0 24px;
+      background: #ffffff;
+      border-bottom: 1px solid #d9e1ec;
+      position: sticky;
+      top: 0;
+      z-index: 3;
+    }
+    h1 { font-size: 18px; margin: 0; letter-spacing: 0; }
+    .header-actions { display: flex; align-items: center; gap: 12px; }
+    .auto-refresh {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      color: #506176;
+      font-size: 13px;
+    }
+    button {
+      border: 1px solid #c9d3e2;
+      background: #ffffff;
+      color: #132033;
+      border-radius: 6px;
+      padding: 8px 12px;
+      cursor: pointer;
+      font-size: 13px;
+    }
+    button.active { background: #1d4ed8; color: #ffffff; border-color: #1d4ed8; }
+    main {
+      display: grid;
+      grid-template-columns: 360px minmax(0, 1fr);
+      min-height: calc(100vh - 65px);
+    }
+    aside {
+      border-right: 1px solid #d9e1ec;
+      background: #f8fafc;
+      overflow-y: auto;
+      max-height: calc(100vh - 65px);
+    }
+    .roots { padding: 14px 16px; font-size: 12px; color: #506176; border-bottom: 1px solid #d9e1ec; }
+    .sidebar-section-title {
+      padding: 12px 16px 7px;
+      color: #64748b;
+      font-size: 11px;
+      font-weight: 800;
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+    }
+    .experiment {
+      padding: 12px 16px;
+      border-bottom: 1px solid #e3e9f2;
+      cursor: pointer;
+      background: #ffffff;
+    }
+    .experiment:hover, .experiment.selected { background: #e8f5ef; }
+    .experiment-title { font-weight: 800; font-size: 13px; margin-bottom: 6px; }
+    .task {
+      padding: 14px 16px;
+      border-bottom: 1px solid #e3e9f2;
+      cursor: pointer;
+    }
+    .task:hover, .task.selected { background: #eaf1ff; }
+    .task-title { font-weight: 700; font-size: 13px; margin-bottom: 6px; }
+    .meta { font-size: 12px; color: #506176; line-height: 1.45; }
+    .content { padding: 20px; overflow: auto; }
+    .toolbar { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 14px; align-items: center; }
+    .stage-bar {
+      display: flex;
+      gap: 8px;
+      overflow-x: auto;
+      padding-bottom: 8px;
+      margin-bottom: 12px;
+    }
+    .stage-bar button {
+      flex: 0 0 auto;
+      white-space: nowrap;
+    }
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+      gap: 10px;
+      margin-bottom: 16px;
+    }
+    .metric {
+      background: #ffffff;
+      border: 1px solid #d9e1ec;
+      border-radius: 8px;
+      padding: 10px 12px;
+    }
+    .metric-label { font-size: 11px; color: #64748b; margin-bottom: 4px; }
+    .metric-value { font-weight: 800; font-size: 16px; line-height: 1.2; word-break: break-word; }
+    .comparison-panel {
+      background: #ffffff;
+      border: 1px solid #d9e1ec;
+      border-radius: 8px;
+      overflow: hidden;
+      margin-bottom: 16px;
+    }
+    .comparison-panel h2 {
+      margin: 0;
+      padding: 12px 14px;
+      font-size: 13px;
+      border-bottom: 1px solid #e3e9f2;
+    }
+    .table-wrap { overflow-x: auto; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 12px;
+      background: #ffffff;
+    }
+    th, td {
+      padding: 9px 10px;
+      border-bottom: 1px solid #e3e9f2;
+      text-align: left;
+      vertical-align: top;
+      white-space: nowrap;
+    }
+    th {
+      color: #475569;
+      background: #f8fafc;
+      font-weight: 800;
+      position: sticky;
+      top: 0;
+    }
+    td .cell-line { color: #506176; line-height: 1.45; }
+    .compact-button { padding: 5px 8px; font-size: 12px; margin-top: 5px; }
+    .task-col { min-width: 220px; max-width: 280px; white-space: normal; }
+    .method-col { min-width: 260px; width: 320px; white-space: normal; }
+    .method-cell {
+      display: grid;
+      gap: 8px;
+      min-width: 240px;
+    }
+    .method-thumb-wrap {
+      height: 180px;
+      border: 1px solid #d9e1ec;
+      border-radius: 6px;
+      background-color: #dfe6f0;
+      background-image:
+        linear-gradient(45deg, rgba(100, 116, 139, 0.18) 25%, transparent 25%),
+        linear-gradient(-45deg, rgba(100, 116, 139, 0.18) 25%, transparent 25%),
+        linear-gradient(45deg, transparent 75%, rgba(100, 116, 139, 0.18) 75%),
+        linear-gradient(-45deg, transparent 75%, rgba(100, 116, 139, 0.18) 75%);
+      background-size: 18px 18px;
+      background-position: 0 0, 0 9px, 9px -9px, -9px 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      overflow: hidden;
+    }
+    .method-thumb {
+      max-width: 100%;
+      max-height: 100%;
+      object-fit: contain;
+      background: transparent;
+    }
+    .method-metrics {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 5px;
+    }
+    .method-metric {
+      border: 1px solid #e3e9f2;
+      border-radius: 6px;
+      padding: 5px 6px;
+      background: #f8fafc;
+    }
+    .method-metric-label {
+      color: #64748b;
+      font-size: 10px;
+      line-height: 1.1;
+    }
+    .method-metric-value {
+      margin-top: 2px;
+      font-size: 12px;
+      font-weight: 800;
+      color: #132033;
+      line-height: 1.15;
+    }
+    .viewer-grid {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 360px;
+      gap: 16px;
+      align-items: start;
+    }
+    .image-panel, .detail-panel {
+      background: #ffffff;
+      border: 1px solid #d9e1ec;
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .stage-files {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 12px;
+      padding: 12px;
+    }
+    .stage-file {
+      border: 1px solid #e3e9f2;
+      border-radius: 8px;
+      overflow: hidden;
+      background: #ffffff;
+    }
+    .stage-file h3 {
+      margin: 0;
+      padding: 9px 10px;
+      font-size: 12px;
+      border-bottom: 1px solid #e3e9f2;
+      color: #334155;
+    }
+    .stage-file .image-wrap { min-height: 180px; padding: 8px; }
+    .stage-file img { max-height: 320px; }
+    .stage-file pre {
+      max-height: 320px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+    .image-panel h2, .detail-panel h2 {
+      margin: 0;
+      padding: 12px 14px;
+      font-size: 13px;
+      border-bottom: 1px solid #e3e9f2;
+    }
+    .image-wrap {
+      background-color: #dfe6f0;
+      background-image:
+        linear-gradient(45deg, rgba(100, 116, 139, 0.22) 25%, transparent 25%),
+        linear-gradient(-45deg, rgba(100, 116, 139, 0.22) 25%, transparent 25%),
+        linear-gradient(45deg, transparent 75%, rgba(100, 116, 139, 0.22) 75%),
+        linear-gradient(-45deg, transparent 75%, rgba(100, 116, 139, 0.22) 75%);
+      background-size: 20px 20px;
+      background-position: 0 0, 0 10px, 10px -10px, -10px 0;
+      padding: 12px;
+      min-height: 320px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    img {
+      display: block;
+      max-width: 100%;
+      max-height: calc(100vh - 260px);
+      object-fit: contain;
+      background: transparent;
+    }
+    pre {
+      margin: 0;
+      padding: 12px;
+      max-height: 360px;
+      overflow: auto;
+      font-size: 12px;
+      line-height: 1.45;
+      background: #0f172a;
+      color: #dbeafe;
+    }
+    .candidate-list { display: grid; gap: 8px; padding: 12px; }
+    .candidate {
+      border: 1px solid #d9e1ec;
+      border-radius: 8px;
+      padding: 10px;
+      cursor: pointer;
+      background: #ffffff;
+    }
+    .candidate.active { border-color: #1d4ed8; box-shadow: 0 0 0 2px rgba(29, 78, 216, 0.12); }
+    .tags { margin-top: 6px; display: flex; flex-wrap: wrap; gap: 4px; }
+    .tag { background: #fee2e2; color: #991b1b; border-radius: 4px; padding: 2px 5px; font-size: 11px; }
+    .tag.warn { background: #fef3c7; color: #92400e; }
+    .prompt-card {
+      padding: 12px;
+      border-bottom: 1px solid #e3e9f2;
+      background: #fbfdff;
+    }
+    .prompt-actions {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      margin-bottom: 10px;
+    }
+    .prompt-title { font-weight: 700; font-size: 12px; color: #334155; }
+    .prompt-text {
+      max-height: 360px;
+      overflow: auto;
+      border: 1px solid #d9e1ec;
+      border-radius: 8px;
+      background: #ffffff;
+      padding: 12px;
+      font-size: 13px;
+      line-height: 1.62;
+      color: #172033;
+    }
+    .prompt-paragraph { margin: 0 0 12px; }
+    .prompt-paragraph:last-child { margin-bottom: 0; }
+    .json-viewer .prompt-card {
+      border-bottom: 0;
+      padding: 0 0 10px;
+      background: transparent;
+    }
+    .json-viewer .prompt-text { max-height: 280px; }
+    .empty { padding: 24px; color: #64748b; }
+    @media (max-width: 980px) {
+      main { grid-template-columns: 1fr; }
+      aside { max-height: 260px; border-right: 0; border-bottom: 1px solid #d9e1ec; }
+      .viewer-grid { grid-template-columns: 1fr; }
+      .summary { grid-template-columns: repeat(2, minmax(120px, 1fr)); }
+      .stage-files { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>FCI Infographic Viewer</h1>
+    <div class="header-actions">
+      <label class="auto-refresh"><input id="auto-refresh" type="checkbox" checked>Auto 5s</label>
+      <button id="refresh">Refresh</button>
+    </div>
+  </header>
+  <main>
+    <aside>
+      <div class="roots" id="roots">Loading...</div>
+      <div id="tasks"></div>
+    </aside>
+    <section class="content" id="content">
+      <div class="empty">Select a pipeline result.</div>
+    </section>
+  </main>
+  <script>
+    let reports = [];
+    let selectedReport = null;
+    let selectedCandidate = null;
+    let selectedExperimentId = null;
+    let selectedStageIndex = 0;
+    let loadingReports = false;
+    let refreshTimer = null;
+    let viewerVersion = null;
+    let lastRootsHtml = "";
+    let lastTaskListSignature = "";
+    let lastExperimentContentSignature = "";
+    const jsonCache = new Map();
+
+    const assetUrl = (path, version) => {
+      const suffix = version ? "&v=" + encodeURIComponent(version) : "";
+      return "/asset?path=" + encodeURIComponent(path) + suffix;
+    };
+    const fmt = (value) => value === undefined || value === null || value === "" ? "-" : value;
+    const fmtNum = (value) => {
+      if (value === undefined || value === null || value === "") return "-";
+      const number = Number(value);
+      if (!Number.isFinite(number)) return String(value);
+      return Math.abs(number) >= 100 ? number.toFixed(1) : number.toFixed(3).replace(/\.?0+$/, "");
+    };
+    const esc = (value) => String(value ?? "").replace(/[&<>"']/g, (ch) => ({
+      "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"
+    }[ch]));
+    const avg = (values) => {
+      const numbers = values.map(Number).filter(Number.isFinite);
+      if (!numbers.length) return null;
+      return numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
+    };
+    const clampScore = (value) => Math.max(0, Math.min(100, Number(value)));
+    const fallbackFaithfulnessFromMeasurements = (measurements) => {
+      if (!measurements || measurements.chart_pixel_change_score === undefined) return undefined;
+      const pixel = clampScore(100 - 4 * Number(measurements.chart_pixel_change_score || 0));
+      const shape = clampScore(100 - 2 * Number(measurements.chart_deformation_score || 0));
+      const position = clampScore(100 - 3 * Number(measurements.chart_displacement_score || 0));
+      const coverage = clampScore(100 - 2 * Number(measurements.chart_coverage_loss_score || 0));
+      let score = 0.65 * pixel + 0.15 * shape + 0.12 * position + 0.08 * coverage;
+      if (measurements.chart_alignment_reliable === false) score = Math.min(score, 45);
+      return score;
+    };
+    const candidateMeasurements = (candidate) => ((candidate || {}).metadata || {}).measurements || {};
+    const candidateChartFaithfulness = (candidate) => {
+      const metadata = ((candidate || {}).metadata || {});
+      const score = (candidate || {}).score || {};
+      const summary = metadata.chart_faithfulness || {};
+      const measurements = metadata.measurements || {};
+      return score.chart_faithfulness_score
+        ?? summary.score
+        ?? measurements.chart_faithfulness_score
+        ?? fallbackFaithfulnessFromMeasurements(measurements);
+    };
+    const candidateInfographicQuality = (candidate) => {
+      const metadata = ((candidate || {}).metadata || {});
+      const score = (candidate || {}).score || {};
+      const summary = metadata.infographic_quality || {};
+      const quality = candidateQualityScores(candidate);
+      if (score.infographic_quality_score !== undefined && score.infographic_quality_score !== null) return score.infographic_quality_score;
+      if (summary.score !== undefined && summary.score !== null) return summary.score;
+      if (quality.overall_quality !== undefined && quality.overall_quality !== null) return Number(quality.overall_quality) * 20;
+      return undefined;
+    };
+    const candidateQualityScores = (candidate) => ((((candidate || {}).metadata || {}).quality_evaluation || {}).scores || {});
+    const candidateQualityOverall = (candidate) => {
+      const score = (candidate || {}).score || {};
+      const quality = candidateQualityScores(candidate);
+      return score.gpt_quality_overall ?? quality.overall_quality;
+    };
+    const reportBestMeasurements = (report) => candidateMeasurements((report || {}).best);
+    const reportMetric = (report, key) => {
+      if (key === "overall") return (report.best || {}).overall;
+      if (key === "gpt_quality_overall") return candidateQualityOverall((report || {}).best);
+      if (key === "chart_faithfulness_score") return candidateChartFaithfulness((report || {}).best);
+      if (key === "infographic_quality_score") return candidateInfographicQuality((report || {}).best);
+      return reportBestMeasurements(report)[key];
+    };
+    const experimentIdForReport = (report) => report.experiment_id || report.root || "Ungrouped";
+    const variantIdForReport = (report) => report.variant_id || report.pipeline_mode || "variant";
+    const buildExperimentGroups = () => {
+      const groups = new Map();
+      reports.forEach((report, index) => {
+        const id = experimentIdForReport(report);
+        if (!groups.has(id)) {
+          groups.set(id, {id, reports: [], variants: new Map(), latest: 0});
+        }
+        const group = groups.get(id);
+        group.reports.push({report, index});
+        group.latest = Math.max(group.latest, Number(report.updated_mtime_ns || 0));
+        const variantId = variantIdForReport(report);
+        if (!group.variants.has(variantId)) group.variants.set(variantId, []);
+        group.variants.get(variantId).push({report, index});
+      });
+      return Array.from(groups.values()).sort((a, b) => b.latest - a.latest || a.id.localeCompare(b.id));
+    };
+    const experimentContentSignature = (experimentId) => reports
+      .filter((report) => experimentIdForReport(report) === experimentId)
+      .map((report) => [
+        report.id,
+        report.version,
+        report.state,
+        report.stage,
+        report.updated_mtime_ns,
+        report.best?.final_path || "",
+        report.best?.overall || "",
+        report.best?.candidate_id || ""
+      ].join(":"))
+      .sort()
+      .join("|");
+    const variantSortKey = (variantId) => {
+      if (variantId.includes("baseline")) return "00_" + variantId;
+      if (variantId === "full") return "01_" + variantId;
+      return "10_" + variantId;
+    };
+    const variantRows = (group) => Array.from(group.variants.entries())
+      .sort(([a], [b]) => variantSortKey(a).localeCompare(variantSortKey(b)))
+      .map(([variantId, entries]) => ({variantId, entries}));
+    const alignmentLine = (candidate) => {
+      const measurements = candidateMeasurements(candidate);
+      if (!measurements.chart_alignment_method) return "";
+      return "align " + fmt(measurements.chart_alignment_method)
+        + " | reliable " + fmt(measurements.chart_alignment_reliable)
+        + " | scale " + fmt(measurements.chart_alignment_scale)
+        + " | change " + fmt(measurements.chart_change_score)
+        + " | deform " + fmt(measurements.chart_deformation_score);
+    };
+    const renderAlignmentMeta = (candidate) => {
+      const line = alignmentLine(candidate);
+      return line ? `<br><span class="meta">${esc(line)}</span>` : "";
+    };
+    const renderCandidateTags = (candidate) => {
+      const tags = (candidate.failure_tags || []).map((tag) => `<span class="tag">${esc(tag)}</span>`);
+      const measurements = candidateMeasurements(candidate);
+      if (measurements.chart_alignment_reliable === false) {
+        tags.push('<span class="tag warn">low-confidence alignment</span>');
+      }
+      return tags.join("");
+    };
+    const normalizePrompt = (value) => String(value ?? "")
+      .replace(/\r\n/g, "\n")
+      .replace(/\\n/g, "\n");
+    const renderPromptBody = (prompt) => {
+      const normalized = normalizePrompt(prompt).trim();
+      const paragraphs = normalized.split(/\n\s*\n/g).map((part) => part.trim()).filter(Boolean);
+      return paragraphs.map((paragraph) => {
+        const lines = paragraph.split(/\n/g).map((line) => line.trim()).filter(Boolean);
+        return `<p class="prompt-paragraph">${lines.map(esc).join("<br>")}</p>`;
+      }).join("");
+    };
+    const renderPromptCard = (prompt, title, actionsHtml = "") => {
+      const normalized = normalizePrompt(prompt);
+      if (!normalized.trim()) return '<div class="prompt-card"><div class="empty">No prompt recorded.</div></div>';
+      return `
+        <div class="prompt-card">
+          <div class="prompt-actions">
+            <div class="prompt-title">${esc(title)} (${normalized.length} chars)</div>
+            ${actionsHtml}
+          </div>
+          <div class="prompt-text">
+            ${renderPromptBody(normalized)}
+          </div>
+        </div>
+      `;
+    };
+    const selectedPrompt = () => normalizePrompt((selectedCandidate || selectedReport?.best || {}).prompt || "");
+    const renderSelectedPromptCard = () => renderPromptCard(
+      selectedPrompt(),
+      "Selected Prompt",
+      '<button onclick="copySelectedPrompt(event)">Copy Prompt</button>'
+    );
+    const extractPromptPreview = (payload) => {
+      if (!payload || typeof payload !== "object") return "";
+      for (const key of ["prompt", "final_prompt", "image_prompt", "instructions"]) {
+        if (typeof payload[key] === "string" && payload[key].trim()) return payload[key];
+      }
+      for (const key of ["variants", "prompts", "candidates"]) {
+        if (!Array.isArray(payload[key])) continue;
+        const parts = payload[key].map((item, index) => {
+          if (!item || typeof item !== "object") return "";
+          const prompt = item.prompt || item.final_prompt || item.image_prompt || item.instructions || "";
+          if (!String(prompt).trim()) return "";
+          const label = item.variant_id || item.id || item.name || `variant_${index}`;
+          return `${label}\n${prompt}`;
+        }).filter(Boolean);
+        if (parts.length) return parts.join("\n\n");
+      }
+      return "";
+    };
+    const renderJsonPayload = (text) => {
+      let rendered = text;
+      let prompt = "";
+      try {
+        const payload = JSON.parse(text);
+        rendered = JSON.stringify(payload, null, 2);
+        prompt = extractPromptPreview(payload);
+      } catch {
+      }
+      return `${prompt ? renderPromptCard(prompt, "Prompt Preview") : ""}<pre>${esc(rendered)}</pre>`;
+    };
+    async function copySelectedPrompt(event) {
+      event.stopPropagation();
+      const prompt = selectedPrompt();
+      if (!prompt) return;
+      try {
+        await navigator.clipboard.writeText(prompt);
+        event.target.textContent = "Copied";
+        setTimeout(() => { event.target.textContent = "Copy Prompt"; }, 1000);
+      } catch {
+        event.target.textContent = "Copy failed";
+        setTimeout(() => { event.target.textContent = "Copy Prompt"; }, 1000);
+      }
+    }
+
+    async function loadReports(options = {}) {
+      if (loadingReports) return;
+      loadingReports = true;
+      try {
+        const forceContent = Boolean(options.forceContent);
+        const response = await fetch("/api/reports");
+        const data = await response.json();
+        const previousReportId = selectedReport?.id;
+        const previousReportVersion = selectedReport?.version;
+        const previousCandidateId = selectedCandidate?.candidate_id;
+        const previousExperimentId = selectedExperimentId;
+        reports = data.reports || [];
+        const modeLine = "latest root: " + esc(data.show_all_roots ? "off" : "on")
+          + " | legacy: " + esc(data.include_legacy ? "shown" : "hidden");
+        const rootsHtml = "<b>Roots</b> (" + reports.length + " reports)<br>"
+          + modeLine + "<br>"
+          + (data.roots || []).map(esc).join("<br>");
+        if (rootsHtml !== lastRootsHtml) {
+          document.getElementById("roots").innerHTML = rootsHtml;
+          lastRootsHtml = rootsHtml;
+        }
+        renderTasks();
+        if (!reports.length) {
+          selectedReport = null;
+          selectedCandidate = null;
+          selectedExperimentId = null;
+          renderContent();
+        } else if (!selectedReport && !selectedExperimentId && reports.length) {
+          const groups = buildExperimentGroups();
+          if (groups.length) {
+            selectExperiment(groups[0].id);
+          } else {
+            selectReport(reports[0].id);
+          }
+        } else if (selectedExperimentId && !selectedReport) {
+          const groups = buildExperimentGroups();
+          if (!groups.find((group) => group.id === previousExperimentId)) {
+            selectedExperimentId = groups[0]?.id || null;
+          }
+          renderTasks();
+          const nextExperimentSignature = selectedExperimentId ? experimentContentSignature(selectedExperimentId) : "";
+          if (forceContent || nextExperimentSignature !== lastExperimentContentSignature) {
+            renderContent();
+          }
+        } else if (selectedReport) {
+          const nextReport = reports.find((item) => item.id === previousReportId) || reports[0] || null;
+          const contentChanged = forceContent
+            || !nextReport
+            || nextReport.id !== previousReportId
+            || nextReport.version !== previousReportVersion;
+          selectedReport = nextReport;
+          selectedCandidate = selectedReport?.candidates.find((candidate) => candidate.candidate_id === previousCandidateId)
+            || selectedReport?.best
+            || null;
+          selectedExperimentId = selectedReport ? experimentIdForReport(selectedReport) : null;
+          selectedStageIndex = Math.min(selectedStageIndex, Math.max(0, (selectedReport?.stages || []).length - 1));
+          renderTasks();
+          if (contentChanged) renderContent();
+        }
+      } finally {
+        loadingReports = false;
+      }
+    }
+
+    function renderTasks(force = false) {
+      const node = document.getElementById("tasks");
+      if (!reports.length) {
+        if (force || lastTaskListSignature !== "empty") {
+          node.innerHTML = '<div class="empty">No report.json files found under configured output roots.</div>';
+          lastTaskListSignature = "empty";
+        }
+        return;
+      }
+      const signature = reports.map((report) => [
+        report.id,
+        report.version,
+        report.state,
+        report.stage,
+        report.experiment_id,
+        report.variant_id,
+        selectedExperimentId === experimentIdForReport(report) ? "experiment" : "",
+        selectedReport && selectedReport.id === report.id ? "selected" : ""
+      ].join(":")).join("|");
+      if (!force && signature === lastTaskListSignature) return;
+      lastTaskListSignature = signature;
+      const groups = buildExperimentGroups();
+      const visibleReports = selectedExperimentId
+        ? reports.map((report, index) => ({report, index})).filter(({report}) => experimentIdForReport(report) === selectedExperimentId)
+        : reports.map((report, index) => ({report, index}));
+      node.innerHTML = `
+        <div class="sidebar-section-title">Experiments</div>
+        ${groups.map((group) => {
+          const overall = avg(group.reports.map(({report}) => reportMetric(report, "overall")));
+          const faithfulness = avg(group.reports.map(({report}) => reportMetric(report, "chart_faithfulness_score")));
+          const quality = avg(group.reports.map(({report}) => reportMetric(report, "infographic_quality_score")));
+          const change = avg(group.reports.map(({report}) => reportMetric(report, "chart_change_score")));
+          return `
+            <div class="experiment ${selectedExperimentId === group.id && !selectedReport ? "selected" : ""}" onclick="selectExperiment(${JSON.stringify(group.id).replace(/"/g, "&quot;")})">
+              <div class="experiment-title">${esc(group.id)}</div>
+              <div class="meta">
+                variants: ${esc(group.variants.size)} | reports: ${esc(group.reports.length)}<br>
+                overall ${esc(fmtNum(overall))} | faith ${esc(fmtNum(faithfulness))} | info ${esc(fmtNum(quality))} | change ${esc(fmtNum(change))}
+              </div>
+            </div>
+          `;
+        }).join("") || '<div class="empty">No experiments found.</div>'}
+        <div class="sidebar-section-title">${selectedExperimentId ? "Reports In Experiment" : "Recent Reports"}</div>
+        ${visibleReports.map(({report, index}) => `
+        <div class="task ${selectedReport && selectedReport.id === report.id ? "selected" : ""}" onclick="selectReportByIndex(${index})">
+          <div class="task-title">${esc(report.task_id)}</div>
+          <div class="meta">
+            mode: ${esc(report.pipeline_mode)}<br>
+            variant: ${esc(report.variant_id || "-")}<br>
+            agent: ${esc(report.agent_mode)} / ${esc(report.agent_model)}<br>
+            generator: ${esc(report.generator)}<br>
+            state: ${esc(report.state)} / ${esc(report.stage)}<br>
+            source: ${esc(report.source_kind)} / ${esc(report.effective_alpha_mode)}<br>
+            best: ${esc(report.best.variant_id)} / ${esc(report.best.overall)}<br>
+            ${esc(report.task_dir)}
+          </div>
+        </div>
+      `).join("") || '<div class="empty">No reports in this experiment.</div>'}
+      `;
+    }
+
+    function selectExperiment(id) {
+      selectedExperimentId = id;
+      selectedReport = null;
+      selectedCandidate = null;
+      selectedStageIndex = 0;
+      lastExperimentContentSignature = "";
+      renderTasks(true);
+      renderContent();
+    }
+
+    function selectReportByIndex(index) {
+      selectedReport = reports[index] || null;
+      selectedCandidate = selectedReport?.best || null;
+      selectedExperimentId = selectedReport ? experimentIdForReport(selectedReport) : null;
+      selectedStageIndex = 0;
+      lastExperimentContentSignature = "";
+      renderTasks(true);
+      renderContent();
+    }
+
+    function selectReport(id) {
+      selectedReport = reports.find((item) => item.id === id);
+      selectedCandidate = selectedReport?.best || null;
+      selectedExperimentId = selectedReport ? experimentIdForReport(selectedReport) : null;
+      selectedStageIndex = 0;
+      lastExperimentContentSignature = "";
+      renderTasks(true);
+      renderContent();
+    }
+
+    function selectCandidate(index) {
+      selectedCandidate = selectedReport.candidates[index];
+      renderContent();
+    }
+
+    function selectStage(index) {
+      selectedStageIndex = index;
+      renderContent();
+    }
+
+    function renderContent() {
+      const node = document.getElementById("content");
+      if (selectedExperimentId && !selectedReport) {
+        renderExperimentContent(node);
+        return;
+      }
+      if (!selectedReport) {
+        node.innerHTML = '<div class="empty">No result selected.</div>';
+        return;
+      }
+      const stages = selectedReport.stages || [];
+      const selectedStage = stages[selectedStageIndex] || stages[0] || null;
+      const bestMeasurements = candidateMeasurements(selectedReport.best);
+      const bestFaithfulness = candidateChartFaithfulness(selectedReport.best);
+      const bestInfographicQuality = candidateInfographicQuality(selectedReport.best);
+      node.innerHTML = `
+        <div class="summary">
+          <div class="metric"><div class="metric-label">Best Overall</div><div class="metric-value">${esc(selectedReport.best.overall)}</div></div>
+          <div class="metric"><div class="metric-label">Faithfulness</div><div class="metric-value">${esc(fmtNum(bestFaithfulness))}</div></div>
+          <div class="metric"><div class="metric-label">Infographic</div><div class="metric-value">${esc(fmtNum(bestInfographicQuality))}</div></div>
+          <div class="metric"><div class="metric-label">Alignment</div><div class="metric-value">${esc(bestMeasurements.chart_alignment_method || "-")}</div></div>
+          <div class="metric"><div class="metric-label">Reliable / Scale</div><div class="metric-value">${esc(fmt(bestMeasurements.chart_alignment_reliable))} / ${esc(fmt(bestMeasurements.chart_alignment_scale))}</div></div>
+          <div class="metric"><div class="metric-label">Change Score</div><div class="metric-value">${esc(fmt(bestMeasurements.chart_change_score))}</div></div>
+          <div class="metric"><div class="metric-label">Pixel / Deform / Move</div><div class="metric-value">${esc(fmt(bestMeasurements.chart_pixel_change_score))} / ${esc(fmt(bestMeasurements.chart_deformation_score))} / ${esc(fmt(bestMeasurements.chart_displacement_score))}</div></div>
+          <div class="metric"><div class="metric-label">State</div><div class="metric-value">${esc(selectedReport.state)} / ${esc(selectedReport.stage)}</div></div>
+        </div>
+        <div class="stage-bar">
+          ${stages.map((stage, index) => `<button class="${selectedStageIndex === index ? "active" : ""}" onclick="selectStage(${index});">${esc(stage.label)}</button>`).join("")}
+        </div>
+        <div class="viewer-grid">
+          <div class="image-panel">
+            <h2>${esc(selectedStage ? selectedStage.label : "Pipeline Stage")}</h2>
+            ${renderStageFiles(selectedStage)}
+          </div>
+          <div class="detail-panel">
+            <h2>Candidates</h2>
+            <div class="candidate-list">
+              ${(selectedReport.candidates || []).map((candidate, index) => `
+                <div class="candidate ${selectedCandidate && selectedCandidate.candidate_id === candidate.candidate_id ? "active" : ""}" onclick="selectCandidate(${index})">
+                  <b>#${esc(candidate.candidate_id)} ${esc(candidate.variant_id)}</b><br>
+                  <span class="meta">overall ${esc(candidate.overall)} | faith ${esc(fmtNum(candidateChartFaithfulness(candidate)))} | info ${esc(fmtNum(candidateInfographicQuality(candidate)))}</span>
+                  ${renderAlignmentMeta(candidate)}
+                  <div class="tags">${renderCandidateTags(candidate)}</div>
+                </div>
+              `).join("") || '<div class="empty">No candidates yet.</div>'}
+            </div>
+            <h2>Selected Prompt</h2>
+            ${renderSelectedPromptCard()}
+            <h2>Selected Candidate JSON</h2>
+            <pre>${esc(JSON.stringify(selectedCandidate || selectedReport.best, null, 2))}</pre>
+            ${selectedReport.error ? `<h2>Error</h2><pre>${esc(JSON.stringify(selectedReport.error, null, 2))}</pre>` : ""}
+          </div>
+        </div>
+      `;
+      hydrateJsonFiles();
+    }
+
+    function renderExperimentContent(node) {
+      const group = buildExperimentGroups().find((item) => item.id === selectedExperimentId);
+      if (!group) {
+        lastExperimentContentSignature = "";
+        node.innerHTML = '<div class="empty">No experiment selected.</div>';
+        return;
+      }
+      lastExperimentContentSignature = experimentContentSignature(selectedExperimentId);
+      const allReports = group.reports.map(({report}) => report);
+      const overall = avg(allReports.map((report) => reportMetric(report, "overall")));
+      const faithfulness = avg(allReports.map((report) => reportMetric(report, "chart_faithfulness_score")));
+      const quality = avg(allReports.map((report) => reportMetric(report, "infographic_quality_score")));
+      const change = avg(allReports.map((report) => reportMetric(report, "chart_change_score")));
+      node.innerHTML = `
+        <div class="summary">
+          <div class="metric"><div class="metric-label">Experiment</div><div class="metric-value">${esc(group.id)}</div></div>
+          <div class="metric"><div class="metric-label">Variants / Reports</div><div class="metric-value">${esc(group.variants.size)} / ${esc(group.reports.length)}</div></div>
+          <div class="metric"><div class="metric-label">Avg Overall</div><div class="metric-value">${esc(fmtNum(overall))}</div></div>
+          <div class="metric"><div class="metric-label">Avg Faithfulness</div><div class="metric-value">${esc(fmtNum(faithfulness))}</div></div>
+          <div class="metric"><div class="metric-label">Avg Infographic</div><div class="metric-value">${esc(fmtNum(quality))}</div></div>
+          <div class="metric"><div class="metric-label">Avg Change</div><div class="metric-value">${esc(fmtNum(change))}</div></div>
+        </div>
+        <div class="comparison-panel">
+          <h2>Variant Summary</h2>
+          ${renderVariantSummaryTable(group)}
+        </div>
+        <div class="comparison-panel">
+          <h2>Task Comparison</h2>
+          ${renderTaskComparisonTable(group)}
+        </div>
+      `;
+    }
+
+    function renderVariantSummaryTable(group) {
+      const rows = variantRows(group).map(({variantId, entries}) => {
+        const variantReports = entries.map(({report}) => report);
+        return `
+          <tr>
+            <td><b>${esc(variantId)}</b></td>
+            <td>${esc(entries.length)}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "overall")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "chart_faithfulness_score")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "infographic_quality_score")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "chart_change_score")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "chart_pixel_change_score")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "chart_deformation_score")))))}</td>
+            <td>${esc(fmtNum(avg(variantReports.map((report) => reportMetric(report, "chart_displacement_score")))))}</td>
+            <td>${esc(variantReports.filter((report) => reportMetric(report, "chart_alignment_reliable") === false).length)}</td>
+          </tr>
+        `;
+      }).join("");
+      return `
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr>
+                <th>Variant</th>
+                <th>Reports</th>
+                <th>Overall</th>
+                <th>Faithfulness</th>
+                <th>Infographic</th>
+                <th>Change</th>
+                <th>Pixel</th>
+                <th>Deform</th>
+                <th>Move</th>
+                <th>Low Conf</th>
+              </tr>
+            </thead>
+            <tbody>${rows || '<tr><td colspan="10">No variant data.</td></tr>'}</tbody>
+          </table>
+        </div>
+      `;
+    }
+
+    function renderTaskComparisonTable(group) {
+      const variants = variantRows(group);
+      const taskIds = Array.from(new Set(group.reports.map(({report}) => report.task_id))).sort();
+      const byTaskVariant = new Map();
+      group.reports.forEach(({report, index}) => {
+        const taskId = report.task_id;
+        const variantId = variantIdForReport(report);
+        const key = taskId + "\u0000" + variantId;
+        byTaskVariant.set(key, {report, index});
+      });
+      const rows = taskIds.map((taskId) => `
+        <tr>
+          <td class="task-col"><b>${esc(taskId)}</b></td>
+          ${variants.map(({variantId}) => {
+            const entry = byTaskVariant.get(taskId + "\u0000" + variantId);
+            return `<td class="method-col">${entry ? renderComparisonCell(entry) : "-"}</td>`;
+          }).join("")}
+        </tr>
+      `).join("");
+      return `
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr>
+                <th>Task</th>
+                ${variants.map(({variantId}) => `<th>${esc(variantId)}</th>`).join("")}
+              </tr>
+            </thead>
+            <tbody>${rows || `<tr><td colspan="${variants.length + 1}">No task data.</td></tr>`}</tbody>
+          </table>
+        </div>
+      `;
+    }
+
+    function renderComparisonCell(entry) {
+      const report = entry.report;
+      const measurements = reportBestMeasurements(report);
+      const finalPath = (report.best || {}).final_path || "";
+      const imageHtml = finalPath
+        ? `<img class="method-thumb" loading="lazy" decoding="async" src="${assetUrl(finalPath, report.version)}">`
+        : '<div class="empty">No final image</div>';
+      return `
+        <div class="method-cell">
+          <div class="method-thumb-wrap">${imageHtml}</div>
+          <div class="method-metrics">
+            ${renderSmallMetric("Overall", reportMetric(report, "overall"))}
+            ${renderSmallMetric("Faith", reportMetric(report, "chart_faithfulness_score"))}
+            ${renderSmallMetric("Info", reportMetric(report, "infographic_quality_score"))}
+            ${renderSmallMetric("Change", measurements.chart_change_score)}
+            ${renderSmallMetric("Pixel", measurements.chart_pixel_change_score)}
+            ${renderSmallMetric("Deform", measurements.chart_deformation_score)}
+          </div>
+          <div class="cell-line">move ${esc(fmtNum(measurements.chart_displacement_score))} | reliable ${esc(fmt(measurements.chart_alignment_reliable))} | scale ${esc(fmtNum(measurements.chart_alignment_scale))}</div>
+          <button class="compact-button" onclick="selectReportByIndex(${entry.index})">Open Details</button>
+        </div>
+      `;
+    }
+
+    function renderSmallMetric(label, value) {
+      return `
+        <div class="method-metric">
+          <div class="method-metric-label">${esc(label)}</div>
+          <div class="method-metric-value">${esc(fmtNum(value))}</div>
+        </div>
+      `;
+    }
+
+    function renderStageFiles(stage) {
+      if (!stage || !stage.files || !stage.files.length) {
+        return '<div class="empty">No intermediate files for this stage yet.</div>';
+      }
+      return `<div class="stage-files">${stage.files.map((file) => `
+        <div class="stage-file">
+          <h3>${esc(file.label)}</h3>
+          ${renderStageFile(file)}
+        </div>
+      `).join("")}</div>`;
+    }
+
+    function renderStageFile(file) {
+      if (file.type === "image") {
+        return `<div class="image-wrap"><img loading="lazy" decoding="async" src="${assetUrl(file.path, file.version)}"></div>`;
+      }
+      if (file.type === "json") {
+        return `<div class="json-viewer" data-json-path="${esc(file.path)}" data-json-version="${esc(file.version)}"><pre>Loading...</pre></div>`;
+      }
+      return `<pre>${esc(file.path)}</pre>`;
+    }
+
+    async function hydrateJsonFiles() {
+      const nodes = Array.from(document.querySelectorAll(".json-viewer[data-json-path]"));
+      await Promise.all(nodes.map(async (node) => {
+        const path = node.getAttribute("data-json-path");
+        const version = node.getAttribute("data-json-version") || "";
+        const cacheKey = path + "::" + version;
+        if (jsonCache.has(cacheKey)) {
+          node.innerHTML = jsonCache.get(cacheKey);
+          return;
+        }
+        try {
+          const response = await fetch(assetUrl(path, version));
+          const text = await response.text();
+          const rendered = renderJsonPayload(text);
+          jsonCache.set(cacheKey, rendered);
+          node.innerHTML = rendered;
+        } catch (error) {
+          node.innerHTML = `<pre>${esc(error.message)}</pre>`;
+        }
+      }));
+    }
+
+    function setAutoRefresh(enabled) {
+      if (refreshTimer) clearInterval(refreshTimer);
+      refreshTimer = enabled ? setInterval(loadReports, 5000) : null;
+    }
+
+    async function checkViewerVersion() {
+      try {
+        const response = await fetch("/api/viewer-version", {cache: "no-store"});
+        const data = await response.json();
+        if (!data.version) return;
+        if (viewerVersion === null) {
+          viewerVersion = data.version;
+          return;
+        }
+        if (viewerVersion !== data.version) {
+          window.location.reload();
+        }
+      } catch {
+      }
+    }
+
+    document.getElementById("refresh").addEventListener("click", () => loadReports({forceContent: true}));
+    document.getElementById("auto-refresh").addEventListener("change", (event) => {
+      setAutoRefresh(event.target.checked);
+    });
+    setAutoRefresh(true);
+    checkViewerVersion();
+    setInterval(checkViewerVersion, 2000);
+    loadReports({forceContent: true}).catch((error) => {
+      document.getElementById("content").innerHTML = '<div class="empty">' + esc(error.message) + '</div>';
+    });
+  </script>
+</body>
+</html>
+"""
+
+
+def main() -> None:
+    args = parse_args()
+    state = ViewerState(
+        args.output_root or [],
+        args.scan_root,
+        auto_discover=not args.no_auto_discover,
+        show_all_roots=args.show_all_roots,
+        include_legacy=args.show_legacy,
+    )
+    handler = type("FCIInfographicViewerHandler", (ViewerHandler,), {"state": state})
+    server = ThreadingHTTPServer((args.host, args.port), handler)
+    roots = ", ".join(str(root) for root in state.output_roots()) or "(none)"
+    scan_roots = ", ".join(str(root) for root in state.scan_roots) or "(none)"
+    print(f"Serving FCI infographic viewer at http://{args.host}:{args.port}")
+    print(f"Output roots: {html.escape(roots)}")
+    print(f"Scan roots: {html.escape(scan_roots)}")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()