feat(shot): harness default capture fix — bounded networkidle settle after domcontentloaded + blank-frame retry (≤60s wait budget, R7 best-effort preserved); 6 unit tests; lint PASS, 205 unit tests pass via cc-ci-run

runner/harness/screenshot.py

@@ -18,6 +18,7 @@ missing, app slow, navigation error) is swallowed and returns None so the run/ve
 
 from __future__ import annotations
 
+import contextlib
 import os
 
 from . import browser as harness_browser
@@ -28,6 +29,55 @@ VIEWPORT = {"width": 1280, "height": 800}
 # Hard cap so a wedged app can never hang the run on the screenshot step (R7 / Phase-1 timeouts).
 NAV_DEADLINE_S = 45
 
+# ---- post-navigation settle (phase-shot fix, 2026-06-11) ----
+# SPAs (immich, n8n, cryptpad, the keycloak admin console, lasuite-*, mumble-web, mattermost) fire
+# `domcontentloaded` on their empty HTML shell and only paint after the JS bundle loads — snapping
+# immediately produced solid blank frames (byte-stable 4801-2 B) or loading spinners. After nav,
+# wait for network-idle up to SETTLE_TIMEOUT_MS (apps that never go idle — continuous polling —
+# simply spend the cap; bounded, never raises), then RENDER_GRACE_MS for the final paint.
+SETTLE_TIMEOUT_MS = 10_000
+RENDER_GRACE_MS = 500
+# A 1280x800 PNG below this is near-certainly a solid frame or a bare loading spinner (phase-shot
+# audit: blank frames were 4801-2 B across three different apps, lone spinners 5.9-8.8 KB; the
+# smallest real page was 12950 B). One bounded retry with an extra settle, then keep what we get —
+# an honest late frame beats none, and the retry only ever replaces a tiny frame with a later one.
+BLANK_SIZE_BYTES = 10_000
+BLANK_RETRY_SETTLE_MS = 4_000
+# Wait-budget arithmetic (plan-phase-shot §3 P3: step worst case ≤ ~60s): NAV_DEADLINE_S (45s,
+# spent only while the app isn't serving yet) + SETTLE_TIMEOUT_MS + RENDER_GRACE_MS +
+# BLANK_RETRY_SETTLE_MS + RENDER_GRACE_MS = 60s of bounded waiting; tested in unit tests.
+
+
+def _settle(page, idle_timeout_ms: int) -> None:
+    """Best-effort bounded settle: network-idle up to the cap, then a short render grace.
+    Never raises (R7) — a timeout just means the page kept polling; we snap what's painted."""
+    # cosmetic path (R7): a timeout on a never-idle app is expected — the cap IS the wait
+    with contextlib.suppress(Exception):
+        page.wait_for_load_state("networkidle", timeout=idle_timeout_ms)
+    with contextlib.suppress(Exception):
+        page.wait_for_timeout(RENDER_GRACE_MS)
+
+
+def _snap_with_blank_retry(page, out_path: str) -> None:
+    """Screenshot the page; if the PNG is blank/spinner-sized, retry ONCE after a longer settle.
+    The retry overwrites the tiny frame with a strictly-later one (same page, more paint time)."""
+    page.screenshot(path=out_path, full_page=False)
+    try:
+        first = os.path.getsize(out_path)
+    except OSError:
+        return
+    if first >= BLANK_SIZE_BYTES:
+        return
+    print(
+        f"  screenshot: frame looks blank/loading ({first} B < {BLANK_SIZE_BYTES} B) — "
+        "one retry after a longer settle",
+        flush=True,
+    )
+    _settle(page, BLANK_RETRY_SETTLE_MS)
+    page.screenshot(path=out_path, full_page=False)
+    with contextlib.suppress(OSError):
+        print(f"  screenshot: retry frame {os.path.getsize(out_path)} B", flush=True)
+
 
 def screenshot_path(run_artifact_dir: str) -> str:
     """Canonical on-disk path for a run's app screenshot (pure)."""
@@ -79,7 +129,7 @@ def capture(domain: str, out_path: str, *, recipe_meta: dict | None = None) -> s
                     # the uniform ctx convention (rcust P3).
                     hook(page, meta_mod.hook_ctx(domain, recipe_meta))
                     if not os.path.exists(out_path):
-                        page.screenshot(path=out_path, full_page=False)
+                        _snap_with_blank_retry(page, out_path)
                 else:
                     # Default: landing page. Accept any rendered status (200 or an auth redirect to a
                     # login form) — both are credential-free and representative of "the app is up".
@@ -90,7 +140,9 @@ def capture(domain: str, out_path: str, *, recipe_meta: dict | None = None) -> s
                         deadline_seconds=NAV_DEADLINE_S,
                         wait_until="domcontentloaded",
                     )
-                    page.screenshot(path=out_path, full_page=False)
+                    # SPA paint race fix (phase-shot): settle before snapping, retry a blank frame.
+                    _settle(page, SETTLE_TIMEOUT_MS)
+                    _snap_with_blank_retry(page, out_path)
             finally:
                 browser.close()
         if os.path.exists(out_path) and os.path.getsize(out_path) > 0: