Generate README Screenshots

Purpose

The README screenshots in docs/img/*.webp are not manually captured — they are deterministically generated from Storybook stories defined in src/browser/stories/App.readmeScreenshots.stories.tsx. When any of these stories change visually (detected by Chromatic or local inspection), the corresponding WebP assets must be regenerated and committed.

Quick Reference

# 1. Build Storybook
make storybook-build

# 2. Serve the static build (keep running in background)
python3 -m http.server 6006 -d storybook-static &

# 3. Capture all screenshots (3800px, WebP quality 90)
bun run scripts/capture-readme-screenshots.ts

# 4. Capture a single story
bun run scripts/capture-readme-screenshots.ts --story CodeReview

Prerequisites

The capture pipeline requires these tools. If any are missing, stop immediately and report the issue to the user with full detail — do not silently skip or produce degraded output.

Prerequisite Verification

Before running the pipeline, verify all dependencies:

bun --version && \
bun -e "require('playwright'); require('sharp'); console.log('deps ok')" && \
which python3

If any of these fail:

1. Do not proceed with screenshot generation.
2. Report the exact failing command and error to the user.
3. Suggest remediation:
   • Missing playwright: bun add -d playwright && bunx playwright install chromium
   • Missing sharp: bun add -d sharp
   • Missing python3: suggest installing Python or using an alternative static server
   • Missing bun: this is a hard requirement — the entire repo uses bun

Architecture

Resolution & Output

Story → Screenshot Mapping

Key Files

Step-by-Step Procedure

1. Build Storybook

make storybook-build

This produces storybook-static/ in the repo root.

2. Start a Static Server

The capture script expects Storybook at http://localhost:6006. Use a background bash task (not nohup or & in foreground) so the server survives:

# As a background bash task with ~10min lifetime
python3 -m http.server 6006 -d storybook-static

Verify the server is reachable:

bun -e "const r = await fetch('http://localhost:6006'); console.log(r.status)"

Important: curl may succeed when bun fetch fails (different DNS resolution). Always verify with bun -e "fetch(...)" since the capture script uses bun's fetch.

3. Run the Capture Script

bun run scripts/capture-readme-screenshots.ts --storybook-url http://localhost:6006

The script:

• Iterates all 8 stories sequentially
• Opens a fresh Playwright page per story
• Waits for networkidle + 2s stabilization
• Runs playInteraction if defined (with up to 3 retries for flaky interactions)
• Captures full-page PNG, then converts to WebP via Sharp
• Writes to docs/img/<outputFile>

4. Handle Failures

Stories with playInteraction (GitStatusPopover, ContextManagementDialog) can be flaky under sequential load due to UI timing. The script retries each up to 3 times. If failures persist:

# Retry individual failed stories
bun run scripts/capture-readme-screenshots.ts --story GitStatusPopover
bun run scripts/capture-readme-screenshots.ts --story ContextManagementDialog

5. Verify & Commit

# Check all 8 files are present and 3800px wide
for f in code-review agent-status git-status plan-mermaid costs-tab context-management mobile-server-mode orchestrate-agents; do
  bun -e "const s = require('sharp'); const m = await s('docs/img/${f}.webp').metadata(); console.log('${f}:', m.width + 'x' + m.height)"
done

# Stage and commit
git add docs/img/*.webp
git commit -m "regenerate README screenshots at 3800px"

When to Run This

1. Chromatic flags visual changes in any Docs/README Screenshots story
2. Story data changes in App.readmeScreenshots.stories.tsx or mockFactory.ts
3. UI component changes that affect the visual appearance of screenshot stories
4. Explicit user request to refresh README images
5. After rebasing on main when upstream changes affect shared UI components

Troubleshooting

"Storybook is not running"

The capture script verifies Storybook is reachable before starting. Ensure:

• make storybook-build completed successfully
• The static server is running on port 6006
• Verify with bun -e "fetch('http://localhost:6006')" (not just curl)

Interactive stories fail with timeout

Radix popovers/tooltips portal to document.body and require precise hover timing. The retry logic handles most cases. If persistent:

• Run the failing story individually (--story <Name>)
• Check if the story's mock data or selectors drifted from the actual component

Images look wrong (clipped, misaligned)

• Check viewport constants in capture-readme-screenshots.ts (1900×1188, DPR 2)
• Screenshots use viewport-only capture (not fullPage) — if content overflows the viewport, the story layout needs adjustment, not the capture script
• The StoryDef interface supports a postProcess hook for custom Sharp pipelines if a future story needs cropping/compositing, but no current stories use it

Why there is no ProductHero screenshot story

Intentional — README now uses mux-demo.gif as the hero media. The README screenshot pipeline covers only the 9 docs/img/*.webp assets that remain in README, starting with code-review.webp.