feat(cp5): viz.png — per-frame titled PNGs via matplotlib Agg

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

proteus/viz/__init__.py

@@ -6,6 +6,7 @@ panel) or to per-frame PNGs. matplotlib (the `viz` extra) is imported lazily by
 the PNG writer only, so importing this package stays offline-safe.
 """
 
+from proteus.viz.png import write_pngs
 from proteus.viz.reconstruct import (
     FrameMeta,
     FrameStep,
@@ -20,4 +21,5 @@ __all__ = [
     "TraceReconstructionError",
     "reconstruct",
     "render_terminal",
+    "write_pngs",
 ]

proteus/viz/png.py

@@ -0,0 +1,58 @@
+"""Write reconstructed frames as per-frame PNGs (headless, matplotlib Agg).
+
+Each frame is upscaled via the vendored frame_to_rgb_array and saved as
+frame_000.png, frame_001.png ... with a one-line title (turn + action). The rich
+side panel is a terminal feature; PNGs stay clean images with a label. matplotlib
+is the optional `viz` extra and is imported lazily so the offline core never
+needs it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from proteus.arc_grid.rendering import COLOR_MAP, frame_to_rgb_array
+from proteus.viz.reconstruct import FrameStep
+
+
+def _title(step: FrameStep) -> str:
+    meta = step.meta
+    if meta.phase == "cut":
+        return f"Cut {meta.index} (pre-roll)"
+    mark = "✓" if meta.was_congruent else "✗"
+    title = f"Turn {meta.turn_idx}: action={meta.action} {mark}"
+    if meta.terminal:
+        title += f"  [{meta.terminal}]"
+    return title
+
+
+def write_pngs(
+    steps: list[FrameStep],
+    out_dir: Union[str, Path],
+    *,
+    scale: int = 32,
+) -> list[Path]:
+    """Render every frame to `<out_dir>/frame_NNN.png`; return the paths in order."""
+    import matplotlib
+
+    matplotlib.use("Agg")  # headless: no window, no display required
+    import matplotlib.pyplot as plt
+
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths: list[Path] = []
+    for i, step in enumerate(steps):
+        # Real signature: frame_to_rgb_array(steps: int, frame: ndarray,
+        #   scale: int = 4, color_map: Optional[dict] = None) -> ndarray
+        # The first `steps` arg is a display counter (ignored inside the function).
+        rgb = frame_to_rgb_array(0, step.frame, scale, COLOR_MAP)
+        fig, ax = plt.subplots(figsize=(4.0, 4.4))
+        ax.imshow(rgb, interpolation="nearest")
+        ax.axis("off")
+        ax.set_title(_title(step), fontsize=9)
+        path = out_dir / f"frame_{i:03d}.png"
+        fig.savefig(path, dpi=100, bbox_inches="tight")
+        plt.close(fig)
+        paths.append(path)
+    return paths

tests/viz/test_png.py

@@ -0,0 +1,36 @@
+import pytest
+
+pytest.importorskip("matplotlib")  # PNG path needs the `viz` extra
+
+from proteus.agents import VanillaAgent
+from proteus.providers import FakeProvider
+from proteus.runtime.session import SessionRunner
+from proteus.viz import reconstruct, write_pngs
+
+
+def _steps():
+    agent = VanillaAgent(FakeProvider(["ACTION: up"]))
+    trace = SessionRunner(
+        "predator_evade", agent, seed=42, play_turns=4, use_probe=False,
+    ).run()
+    return reconstruct(trace)
+
+
+def test_write_pngs_one_nonempty_file_per_frame(tmp_path):
+    steps = _steps()
+    out_dir = tmp_path / "frames"
+    paths = write_pngs(steps, out_dir)
+    assert len(paths) == len(steps)
+    for p in paths:
+        assert p.exists()
+        assert p.stat().st_size > 0
+    # Files are zero-padded and ordered.
+    assert (out_dir / "frame_000.png").exists()
+
+
+def test_write_pngs_creates_missing_dir(tmp_path):
+    steps = _steps()
+    nested = tmp_path / "a" / "b" / "frames"
+    paths = write_pngs(steps, nested)
+    assert nested.is_dir()
+    assert len(paths) == len(steps)