Frontend-Preview

Provides visual verification for frontend changes before a PR is opened. This is the "kiro hook" equivalent implemented as a skill trigger.

When to Trigger

Trigger frontend-preview when the diff touches:

• *.html, *.css, *.scss, *.tailwind
• *.tsx, *.jsx, *.vue, *.svelte
• *.astro, *.njk, *.hbs
• Any file under frontend/, src/components/, templates/, views/

Workflow

1. Detect Affected Routes

From the diff, infer which routes/pages are affected:

• File src/pages/contributors.tsx → route /contributors
• File src/components/Navbar.tsx → all routes (global component)
• File src/styles/theme.css → all routes

2. Launch Dev Server (if not running)

Dev server detection:

1. Check package.json scripts for a dev server command:

   # Extract script names from package.json
   node -e "const s=require('./package.json').scripts||{}; \
     console.log(Object.keys(s).filter(k=>['dev','start','serve'].includes(k)).join(' '))"

   Common script names: dev, start, serve.
2. Check common ports for an already-running dev server:

   # Check if a dev server is already running on common ports
   for port in 3000 5173 8080 4000 4200 8000 8888; do
     curl -s "http://localhost:$port" >/dev/null 2>&1 && echo "running:$port"
   done

   If a server is already running, use it instead of starting a new one.

3. Framework-specific commands (if detected from dependencies):

   Framework	Detection	Dev command	Default port
   Next.js	next in deps	npm run dev	3000
   Vite	vite in deps	npm run dev	5173
   CRA	react-scripts in deps	npm start	3000
   Vue (Vite)	@vitejs/plugin-vue	npm run dev	5173
   SvelteKit	@sveltejs/kit in deps	npm run dev	5173
   Nuxt	nuxt in deps	npm run dev	3000
   Astro	astro in deps	npm run dev	4321

# Launch the dev server using the detected command
npm run dev  # or: pnpm dev, yarn dev, bun dev

3. Navigate to Affected Route

Use Playwright (or the browser preview tool) to:

1. Navigate to the affected route (e.g., http://localhost:3000/contributors)
2. Capture a screenshot of the current (changed) state

4. Visual Diff (Before/After)

To produce a git-style visual diff on the web:

1. Before: git stash the changes, screenshot the route, git stash pop
2. After: screenshot the route with changes applied
3. Diff: overlay the two screenshots, highlighting changed regions in red (removed) / green (added)

This mimics git diff but for rendered web pages.

Stash safety:

git stash --include-untracked is safe to use when ALL of the following are true:

• git status --porcelain shows only the files related to the current change (no unrelated staged or unstaged modifications)
• No untracked files exist outside the current change set that the stash would clobber
• The working tree has no merge conflicts in progress (git diff --check passes)
• The stash will be popped immediately after the "before" screenshot (no other git operations in between)

Conflict surfacing format:

If git stash pop reports conflicts, stop and surface them to the user:

⚠️  Stash pop conflict detected — manual resolution required.

Conflicted files:
  - <file1>
  - <file2>

Your stashed changes are preserved in the stash stack.
Run `git stash list` to verify, then resolve conflicts manually.

Recovery procedure if stash pop fails:

1. Do NOT force-resolve or discard changes
2. Run git stash list to confirm the stash is still saved
3. Run git status to see conflicted files
4. Surface the conflict list to the user (format above)
5. The user can resolve manually with git checkout --theirs <file> or git checkout --ours <file>, then git stash drop when done
6. If the user wants to abort: git checkout -- . && git stash pop to retry, or git stash apply to apply without dropping
7. Always verify git status returns to the pre-stash state before continuing with the "after" screenshot

5. Screenshot for Vision Review

Capture a screenshot and attach it to the PR so vision-capable models can review the visual change:

# Save screenshot
playwright screenshot --url http://localhost:3000/contributors \
  --output /tmp/frontend-preview.png

The screenshot is referenced in the PR body:

## Frontend Preview
![Preview](screenshot-url-or-attachment)

Lightweight Mode

If Playwright or a dev server is not available, frontend-preview degrades to:

• Listing the affected routes
• Describing the expected visual change based on the diff
• Recommending manual verification

Do NOT block the PR on frontend-preview — it's an enhancement, not a gate.

Playwright Fallback

If Playwright is not available, try alternatives in order:

1. Puppeteer (if installed):

   node -e "const p=require('puppeteer'); \
     (async()=>{const b=await p.launch();const pg=await b.newPage(); \
     await pg.goto('http://localhost:3000/contributors'); \
     await pg.screenshot({path:'/tmp/frontend-preview.png'}); \
     await b.close();})()"

2. Manual screenshot instructions — if no headless browser is available:
   • Report: "No headless browser found (Playwright/Puppeteer). Manual screenshot needed."
   • Provide the URL to screenshot: http://localhost:3000/contributors
   • Instruct the user to take a screenshot and attach it to the PR
3. Always degrade gracefully — never block the PR. If no screenshot can be captured, fall back to Lightweight Mode (list routes + describe changes).

Error Handling

• gh CLI not installed: frontend-preview does not require gh for screenshots. If attaching to a PR fails, save the screenshot locally and instruct the user to attach it manually.
• gh not authenticated: same as above — save screenshot locally.
• GitHub API rate limits: not applicable to screenshot capture. If PR attachment fails due to rate limits, save locally and attach later.
• Dev server not running and cannot start: fall back to Lightweight Mode. Report "Dev server not available — listing affected routes and describing expected changes instead."
• Playwright not installed: see Playwright Fallback above. Try Puppeteer, then manual instructions, then Lightweight Mode.
• Commands fail: if screenshot capture fails (page not found, timeout), record the error and fall back to Lightweight Mode. Do not block the PR.

Integration with PR-Context

If frontend-preview was run:

• Add a ## Frontend Preview section to the PR body
• Attach the screenshot
• Add an AC checkbox: - [ ] Visual change verified on /route

If frontend-preview was NOT run (no frontend changes):

• Skip this phase entirely