Live Preview

/live-preview — Build-Verify-Fix Loop

Prerequisites

This skill requires a screenshot tool. Supported:

• Playwright (recommended): npx playwright screenshot [url] [output.png]
• Puppeteer: via a small script
• Any tool that takes a URL and produces a screenshot

If no screenshot tool is available, this skill will tell you what to install and exit.

When to Use

• Any time .tsx, .jsx, .vue, .svelte, or .html files are modified
• After component creation or replacement
• During visual redesign campaigns
• When Archon or Marshal delegate UI work

Protocol

Step 1: DETECT

Determine what needs visual verification:

1. Check which files were modified in the current session/phase
2. Filter to view-layer files (.tsx, .jsx, .vue, .svelte, .html, .css)
3. If no view-layer files found: exit early with message "No view-layer files modified. Nothing to preview." Skip Steps 2-5. This is expected for non-UI repos (CLI tools, libraries, agent harnesses).
4. Map each modified file to a route or URL where it renders:
   • If the project has a route manifest or sitemap, use it
   • If the project has a dev server, identify which routes render the modified components
   • If you can't determine the route, ask the user

Step 2: CAPTURE

For each route/URL that needs verification:

1. Ensure the dev server is running (start it if not)
2. Take a screenshot:

   npx playwright screenshot http://localhost:{port}/{route} .planning/screenshots/{route-slug}.png --full-page

3. If Playwright isn't available, try:

   # Check for playwright
   npx playwright --version 2>/dev/null
   # If not found, inform the user:
   # "live-preview needs Playwright for screenshots. Install with: npm i -D playwright"

Step 3: VERIFY

For each screenshot:

1. Read the screenshot (vision). Check:
   • Does the component render? (not blank, not invisible)
   • Does it show real data or placeholder/empty states?
   • Are there obvious layout breaks (overlapping elements, overflow, missing sections)?
   • Does it match the intended design direction?
2. Record the result:
   • PASS: renders correctly, matches expectations
   • FAIL: describe what's wrong
   • BLANK: nothing rendered (critical failure)

Step 4: FIX (if failures found)

For each FAIL or BLANK:

1. Diagnose: is it a data issue, a rendering issue, or a missing import?
2. Fix the root cause (not a band-aid)
3. Re-capture and re-verify
4. Maximum 2 fix attempts per component. If still failing, log it and move on.

Step 5: ARTIFACT

Save verification artifacts:

1. Screenshots go to .planning/screenshots/{campaign-slug}/ (if in a campaign) or .planning/screenshots/ (if standalone)
2. In Codex, also register screenshots for the app artifact/browser workflow:

   node scripts/codex-app-artifacts.js record --workflow live-preview --kind screenshot --path ".planning/screenshots/{route-slug}.png" --status pass

3. Verify registered artifacts:

   node scripts/codex-app-artifacts.js verify --require-artifacts

4. Write a verification summary:

   ## Visual Verification: {date}
   
   | Route | File Modified | Result | Notes |
   |-------|--------------|--------|-------|
   | /dashboard | Dashboard.tsx | PASS | Renders correctly |
   | /settings | SettingsPanel.tsx | FAIL → PASS | Fixed missing import, re-verified |
   | /profile | ProfileCard.tsx | BLANK → PASS | Component wasn't mounted, fixed export |