agent-first-screenshots

# Agent-First Screenshots An **agent-first screenshot** is produced by an agent driving the real app via CDP, gated by **structural + pixel + vision verification** before it ships. It turns screenshots from hand-crafted artifacts into a regenerable pipeline. Use this for "take/redo screenshots / make marketing images" tasks. It is NOT e2e evidence — for pass/fail proof use the `fraimz` skill. ## The Zero-Defect Bar **A shippable screenshot has ZERO obvious visual defects** — the bar is not "the content is present", it is: *would a human glancing at it immediately spot something broken?* Overlapping or clipped text, misaligned/collapsed layout, garbled or mid-transition content, blank regions, stray modals/tooltips — any of these disqualifies the frame. Full stop. ## The One Method **Operate the app like a power user preparing a demo, not like a developer hacking the DOM.** The app already looks great: get it into a real, settled state through the UI and capture it cleanly. Never rebuild or fake it. ## Golden Rules 1. **Only remove, never add.** Hiding a leaf distraction (notification badge, "Sign in" footer link, status text) via `display:none` is safe. Never inject fake HTML, override flex/height/width on structural containers, add fixed-position overlays, or mutate the DOM tree — the layout engine will collapse (scroll areas shrink to 0, content disappears). 2. **If a feature isn't available, don't fake it.** Enable it through the settings UI like a real user, or skip the shot and say so. 3. **Each shot starts from a clean reload.** `location.reload()`, wait for full render, navigate through the UI, minimal leaf cleanup, verify, capture. Never carry CSS hacks across shots. 4. **Get state naturally.** Click the real tabs/buttons/pickers; close panels via their close buttons (not CSS); run real multi-turn tasks so content is impressive — no toy data, no mid-stream captures. 5. **Match the target aspect ratio** via CDP metrics override (e.g. 1440x900 at `deviceScaleFactor: 2`), then wait ~1s and re-verify — the override can trigger re-layout. ## Verify with three channels, in a loop `innerText` existing does not mean visible; a healthy DOM rect does not mean it rendered. Every frame must pass all three before it ships: 1. **DOM pre-check (cheap, before capture):** scroll area height > 100px (not collapsed), hero text inside the viewport rect, no unexpected modal/overlay. If it fails: reload and redo — never fix with more CSS. 2. **Pixel post-check (truth, after capture):** decode the PNG and sample the DOM-derived hero rects. Calibration: for text-on-white UI, background ratio is a bad signal (85–92% background is normal). **Variance is the reliable signal**: content-filled region variance > ~200 (often 1000+); blank/flat region < 50. Whole-image `bgRatio > 0.97` → blank frame. 3. **Vision check (mandatory gate):** deterministic stats CANNOT catch the defects that matter most — overlap, clipping, misalignment, double-rendering. Hand the PNG to a vision-capable model with a zero-defect rubric returning JSON: ``` { any_obvious_defect: bool, // the gate — if true, REJECT overlapping_text_or_elements: bool, clipped_or_cutoff: bool, misaligned_or_broken_layout: bool, blank_or_empty_regions: bool, stray_modal_tooltip_or_panel: bool, legible: bool, polish_score: 1-5, defects: ["..."] } ``` If `any_obvious_defect` is true the frame is rejected regardless of layers 1–2. Diagnose, fix the root cause (settle the state, close the picker, reload), recapture. Reusable scripts in this skill's directory: `screenshot-verify.mjs` (verify an existing PNG) and `capture-verify.mjs` (capture at 2x + verify regions + save only on pass); both use `sharp`. ## Common failure modes | Symptom | Fix | |---------|-----| | Overlapping/clipped text (layers 1–2 pass) | Unsettled/edit-mode/wrong-width state — settle, use preview mode, gate on vision | | Blank screenshot / 32px scroll area | Structural element was CSS-hidden — reload, close panels via UI | | Overlay (picker/modal) on every shot | It was opened and never closed — Escape before capturing | | In DOM but not in pixels | Clipped/blank render — trust variance + vision, not `innerText` | ## Anti-patterns Injecting fake components; overriding flex properties; fixed-position overlays; carrying state across shots; verifying via `innerText` only; proof-frame mindset (the goal is "I want that", not "it didn't crash").