Add per-shot overwrite flag to skip existing outputs

Shots default to overwrite=false, skipping re-capture when the output
PNG already exists. Supports per-shot, defaults-level, and --overwrite
CLI override.

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

Author: Kut Akdogan

README.md

@@ -49,6 +49,7 @@ shots run-config --config shots.yaml --use-llm --use-llm-crop --save-source
 | `--use-llm-crop` | off | LLM picks a marketing-friendly crop rectangle |
 | `--max-crop-retries` | `2` | Crop validation retry attempts |
 | `--save-source` | off | Save uncropped source images alongside output |
+| `--overwrite` | off | Force re-capture of all shots, ignoring per-shot `overwrite` settings |
 | `--timeout-ms` | `10000` | Page-load / navigation timeout |
 | `--action-timeout-ms` | `5000` | Timeout for clicks/typing (fail fast) |
 | `--headed` | off | Show the browser window (debug) |
@@ -132,6 +133,7 @@ groups:
 | `defaults.viewport_preset` | top | `desktop` \| `laptop` \| `tablet` \| `mobile` |
 | `defaults.full_page` | top | Capture full scrollable page |
 | `defaults.max_nav_steps` | top | Max LLM navigation steps per shot (default: `12`) |
+| `defaults.overwrite` | top | Default overwrite behavior for all shots (default: `false`) |
 | `shots` | top | Flat list of shots (cannot coexist with `groups`) |
 | `groups` | top | List of shot groups (cannot coexist with `shots`) |
 | `groups[].id` | group | (required) Group identifier |
@@ -146,6 +148,7 @@ groups:
 | `viewport` | shot | Custom `{width, height, scale}` |
 | `full_page` | shot | Override full-page capture for this shot |
 | `label` | shot | Per-shot label override |
+| `overwrite` | shot | If `false` (default), skip when output PNG already exists |
 
 ## Notes
 

shots/cli.py

@@ -20,6 +20,7 @@ def _add_common_run_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument("--use-llm-crop", action="store_true", help="Use LLM to choose a crop box.")
     p.add_argument("--max-crop-retries", type=int, default=2, help="Max crop validation retries (default: 2).")
     p.add_argument("--save-source", action="store_true", help="Save uncropped source images too.")
+    p.add_argument("--overwrite", action="store_true", help="Force re-capture of all shots, ignoring per-shot overwrite settings.")
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -97,6 +98,7 @@ def cmd_run_config(args) -> None:
         use_llm_crop=args.use_llm_crop,
         max_crop_retries=args.max_crop_retries,
         save_source=args.save_source,
+        overwrite_all=args.overwrite,
         cli_fallback_viewport=fallback,
     )
     print(f"Report: {report_path}")

shots/config.py

@@ -20,6 +20,7 @@ class ShotSpec:
     viewport: dict[str, int] | None = None  # width/height/scale
     full_page: bool | None = None
     label: str | None = None  # per-shot label override
+    overwrite: bool | None = None  # skip if output exists (default: False via defaults)
 
 
 @dataclass
@@ -66,6 +67,7 @@ def _parse_shot(s: dict[str, Any], ctx: str) -> ShotSpec:
         viewport={k: int(v) for k, v in viewport.items()} if viewport else None,
         full_page=bool(s["full_page"]) if "full_page" in s else None,
         label=str(s["label"]).strip().replace("\\n", "\n") if s.get("label") else None,
+        overwrite=bool(s["overwrite"]) if "overwrite" in s else None,
     )
 
 

shots/runner.py

@@ -241,6 +241,7 @@ def run_config(
     use_llm_crop: bool,
     max_crop_retries: int = 2,
     save_source: bool,
+    overwrite_all: bool = False,
     cli_fallback_viewport: Viewport,
 ) -> pathlib.Path:
     """
@@ -287,6 +288,20 @@ def run_config(
             for shot in group.shots:
                 shot_counter += 1
                 log.info("--- shot %d/%d: %s ---", shot_counter, total_shots, shot.id)
+
+                # Check if we can skip this shot
+                shot_png_path = group_dir / f"{safe_filename(shot.id)}.png"
+                effective_overwrite = shot.overwrite if shot.overwrite is not None else bool(cfg.defaults.get("overwrite", False))
+                if overwrite_all:
+                    effective_overwrite = True
+
+                if not effective_overwrite and shot_png_path.exists():
+                    log.info("[SKIP] %s -> %s (already exists)", shot.id, shot_png_path)
+                    print(f"[SKIP] {shot.id} -> {shot_png_path} (already exists)")
+                    group_report["shots"].append({"id": shot.id, "status": "skipped", "output": str(shot_png_path)})
+                    group_pngs.append(shot_png_path.read_bytes())
+                    continue
+
                 vp = _resolve_viewport_for_shot(cfg.defaults, shot, cli_fallback_viewport)
 
                 context = browser.new_context(
@@ -477,7 +492,6 @@ def run_config(
                         log.info("added label: %s", label_text.replace("\n", " | "))
 
                     # Save individual shot PNG
-                    shot_png_path = group_dir / f"{safe_filename(shot.id)}.png"
                     shot_png_path.write_bytes(out_bytes)
                     group_pngs.append(out_bytes)
 

tests/unit/test_config.py

@@ -189,6 +189,7 @@ def test_shot_spec_defaults(self):
         assert shot.viewport_preset is None
         assert shot.viewport is None
         assert shot.full_page is None
+        assert shot.overwrite is None
 
     def test_shot_spec_with_all_fields(self):
         shot = ShotSpec(
@@ -248,3 +249,35 @@ def test_base_url_trailing_slash_stripped(self, tmp_path):
         path.write_text(json.dumps(config))
         cfg = load_config(str(path))
         assert cfg.base_url == "https://example.com"
+
+
+class TestShotSpecOverwrite:
+    def test_overwrite_true_parsed(self, tmp_path):
+        config: dict[str, Any] = {
+            "base_url": "https://example.com",
+            "shots": [{"id": "test", "description": "test", "overwrite": True}],
+        }
+        path = tmp_path / "config.json"
+        path.write_text(json.dumps(config))
+        cfg = load_config(str(path))
+        assert cfg.groups[0].shots[0].overwrite is True
+
+    def test_overwrite_false_parsed(self, tmp_path):
+        config: dict[str, Any] = {
+            "base_url": "https://example.com",
+            "shots": [{"id": "test", "description": "test", "overwrite": False}],
+        }
+        path = tmp_path / "config.json"
+        path.write_text(json.dumps(config))
+        cfg = load_config(str(path))
+        assert cfg.groups[0].shots[0].overwrite is False
+
+    def test_overwrite_absent_defaults_to_none(self, tmp_path):
+        config: dict[str, Any] = {
+            "base_url": "https://example.com",
+            "shots": [{"id": "test", "description": "test"}],
+        }
+        path = tmp_path / "config.json"
+        path.write_text(json.dumps(config))
+        cfg = load_config(str(path))
+        assert cfg.groups[0].shots[0].overwrite is None