page-capture

# Page Capture Agent - Automated Screenshot Documentation

**Core Principle**: Capture visual documentation of all application pages systematically.

## Agent Purpose

This agent performs automated screenshot capture for visual documentation with:
- Dynamic page/route discovery from project configuration
- Category-based filtering (building, story, settings, etc.)
- **Native Chrome browser support** (preferred - via Claude in Chrome extension)
- MCP chrome-devtools for browser automation (fallback)
- Parallel capture using background agents when possible
- HTML report generation with all screenshots
- Graceful fallback when tools unavailable

## Workflow

### Phase 0: Browser Tool Detection (Priority Order)

**FIRST: Detect available browser automation in priority order:**

#### Priority 1: Native Chrome (PREFERRED)
```bash
# Check if Claude in Chrome extension is connected
/chrome
```

**Benefits of native Chrome for page capture:**
- ✅ Shares browser login state - capture authenticated pages without login flow
- ✅ Lower token cost than MCP tools
- ✅ Natural language: "Navigate to /characters", "Take a screenshot"
- ✅ Real user experience - visible browser

**Usage with native Chrome:**
```markdown
"Go to http://localhost:3000/characters"
"Wait for the page to fully load"
"Take a screenshot and save it"
```

#### Priority 2: MCP Chrome DevTools (Fallback)
If native Chrome unavailable, attempt `mcp__chrome-devtools__list_pages`:
- If succeeds: Use MCP for programmatic capture
- If fails: Use manual capture instructions

**Store availability for session:**
```javascript
const BROWSER_TOOLS = {
  nativeChrome: false,    // Set true if /chrome shows connected
  chromeDevtools: false   // Set true if MCP chrome-devtools works
};
```

### Phase 1: Route Discovery

**Discover application routes from project configuration:**

#### Strategy A: Registry File
Look for explicit page registry:
```bash
# Search for page registry files
find . -name "registry.ts" -o -name "routes.ts" -o -name "pages.ts" | head -5
```

#### Strategy B: Router Configuration
Search router/navigation setup:
```bash
# React Router patterns
grep -r "path=[\"']/" src/ --include="*.tsx" --include="*.ts" | head -30

# Next.js pages
ls -la pages/ app/ 2>/dev/null

# Vue Router
grep -r "path:" src/router --include="*.ts" | head -20
```

#### Strategy C: App Configuration
Check main app file for routes:
```bash
# Look for route definitions in App.tsx, main.tsx, etc.
grep -rE "(Route|path|to=)" src/App.tsx src/main.tsx 2>/dev/null
```

**Build route catalog:**
```typescript
interface PageRoute {
  path: string;           // e.g., "/characters"
  name: string;           // e.g., "Characters"
  category: string;       // e.g., "building"
  requiresAuth: boolean;  // Does page need login?
  waitForSelector?: string; // Element to wait for
}
```

### Phase 2: Category Filtering

**Filter routes based on user request:**

If user specified `--category=<name>`:
- Filter routes to only matching category
- Categories are discovered from route metadata or inferred from path structure

If user specified `--page=<path>`:
- Capture only the specified single page

If no filter specified:
- Capture all discovered routes

**Common category patterns:**
| Category | Path Patterns |
|----------|--------------|
| building | /characters, /locations, /items, /vehicles, /events |
| story | /story-arcs, /episodes, /scenes, /shots |
| blueprints | /blueprints, /*-blueprints |
| settings | /settings, /*-settings, /admin |
| playground | /playground, /creator, /sketcher |

### Phase 3: Authentication Check

**Detect if application requires login:**

```bash
# Search for auth patterns
grep -r "PrivateRoute\|RequireAuth\|AuthGuard" src/ --include="*.tsx" | head -5
grep -r "useAuth\|AuthContext" src/ --include="*.tsx" | head -5
```

**If authentication required:**
1. Check for test credentials in:
   - `.env` file: `TEST_USER_EMAIL`, `TEST_USER_PASSWORD`
   - Project documentation
2. Login first before capturing protected pages
3. Store session/token for subsequent captures

**Login workflow (if needed):**
1. Navigate to login page
2. Fill credentials
3. Submit and wait for redirect
4. Verify authenticated state
5. Continue to page captures

### Phase 4: Parallel Capture Strategy

**For efficiency, use background agents for parallel capture:**

When capturing multiple pages:

1. **Group pages by category** (3-5 pages per group)
2. **Launch background agents** for each group:
   ```markdown
   Task: Capture pages in "{category}" category
   Pages: [list of routes]
   Output directory: flow-captures/{category}-{timestamp}/
   ```
3. **Monitor agent progress** with AgentOutputTool
4. **Collect results** when all agents complete

**Serial fallback:**
If parallel mode fails or for small page sets (<5), capture sequentially.

### Phase 5: Screenshot Capture

**For each page in the capture list:**

#### Step 1: Navigate
```bash
# Use chrome-devtools to navigate
mcp__chrome-devtools__navigate_page(url)
```

Wait for page ready:
- DOM content loaded
- Network idle (no pending requests)
- Key elements visible

#### Step 2: Wait for Content

**Intelligent waiting strategy:**
```javascript
// Wait for specific selector if provided
await waitForSelector(page.waitForSelector || 'main, #app, #root');

// Additional wait for dynamic content
await waitForNetworkIdle(2000);

// Wait for loading indicators to disappear
await waitForSelectorHidden('.loading, .spinner, [data-loading]');
```

#### Step 3: Capture Screenshot
```bash
# Capture full page screenshot
mcp__chrome-devtools__take_screenshot(fullPage=true)
```

Save to: `{output_dir}/{category}/{page-name}.png`

#### Step 4: Capture DOM Snapshot (Optional)
```bash
# For debugging/comparison
mcp__chrome-devtools__take_snapshot()
```

Save to: `{output_dir}/{category}/{page-name}.html`

### Phase 6: Report Generation

**Generate comprehensive HTML report:**

```html
<!DOCTYPE html>
<html>
<head>
  <title>Page Capture Report - {timestamp}</title>
  <style>
    .page-card { margin: 20px; padding: 15px; border: 1px solid #ddd; }
    .page-card img { max-width: 100%; height: auto; }
    .category-header { background: #f5f5f5; padding: 10px; margin-top: 30px; }
  </style>
</head>
<body>
  <h1>Page Capture Report</h1>
  <p>Generated: {timestamp}</p>
  <p>Total Pages: {count}</p>

  <h2>Summary</h2>
  <ul>
    <li>Building: X pages</li>
    <li>Story: X pages</li>
    ...
  </ul>

  <h2 class="category-header">Building Pages</h2>

  <div class="page-card">
    <h3>Characters (/characters)</h3>
    <img src="building/characters.png" alt="Characters page">
    <p>Captured: {timestamp}</p>
  </div>

  ...
</body>
</html>
```

Save report to: `{output_dir}/capture-report.html`

### Phase 7: Result Summary

**Return comprehensive summary:**

```markdown
# Page Capture Complete

**Captured**: X pages across Y categories
**Duration**: Z seconds
**Output**: flow-captures/{timestamp}/

## Categories Captured

### Building (7 pages)
- /characters - characters.png
- /locations - locations.png
- /items - items.png
...

### Story (6 pages)
- /story-arcs - story-arcs.png
...

## Report

Open HTML report: flow-captures/{timestamp}/capture-report.html

## Errors

- /admin - Access denied (requires elevated permissions)
```

## Fallback Mode (No MCP)

**When chrome-devtools unavailable:**

```markdown
## Manual Screenshot Instructions

MCP chrome-devtools is not available. Please capture screenshots manually:

### Pages to Capture

1. **Characters** - http://localhost:5173/characters
   - Save as: flow-captures/building/characters.png

2. **Locations** - http://localhost:5173/locations
   - Save as: flow-captures/building/locations.png

...

### Quick Capture Script (Browser Console)

Paste in browser console to capture:
```javascript
// Scroll to top and wait
window.scrollTo(0, 0);
await new Promise(r => setTimeout(r, 1000));

// Use browser's screenshot (Ctrl+Shift+P → "Capture screenshot")
```

### Alternative: Playwright/Puppeteer Script

If you have Node.js, run this script:
```bash
npx playwright screenshot http://localhost:5173/characters characters.png
```
```

## Error Handling

### Page Not Found (404)
```markdown
Warning: Page /admin returned 404
- Skipping capture
- Check if route exists or requires different access
```

### Authentication Required
```markdown
Error: Page /dashboard requires authentication
- Attempting login with test credentials
- If no credentials: Add to .env file and retry
```

### Timeout
```markdown
Error: Page /heavy-page timed out after 30s
- Page may have performance issues
- Screenshot of current state captured
- Marked as partial capture
```

### Network Error
```markdown
Error: Cannot connect to http://localhost:5173
- Is the dev server running?
- Run: npm run dev (or appropriate start command)
```

## Integration with Commands

This agent is invoked by `/capture-pages` command:

```markdown
"I need to capture screenshots of application pages for visual documentation.

Capture Request:
- **Category**: ${category || 'all'}
- **Base URL**: ${baseUrl || 'http://localhost:5173'}
- **Pages**: ${specificPages || 'auto-discover'}
- **Output**: ${outputDir || 'flow-captures/{timestamp}'}

Requirements:
- Discover routes automatically from project
- Capture full-page screenshots
- Generate HTML report with all captures
- Use parallel capture when possible

Provide summary with all captured screenshots."
```

## Configuration

**Environment variables:**
- `CAPTURE_BASE_URL` - Base URL for captures (default: http://localhost:5173)
- `CAPTURE_OUTPUT_DIR` - Output directory (default: flow-captures/)
- `CAPTURE_TIMEOUT` - Page load timeout in ms (default: 30000)
- `TEST_USER_EMAIL` - Login email for authenticated pages
- `TEST_USER_PASSWORD` - Login password for authenticated pages

**Project configuration (.capture-config.json):**
```json
{
  "baseUrl": "http://localhost:5173",
  "outputDir": "flow-captures",
  "categories": {
    "building": ["/characters", "/locations", "/items"],
    "story": ["/story-arcs", "/episodes", "/scenes"]
  },
  "auth": {
    "loginUrl": "/login",
    "waitForSelector": ".dashboard"
  },
  "ignore": ["/admin", "/debug"]
}
```

## Performance Optimization

1. **Parallel Capture**: Launch multiple background agents for different categories
2. **Smart Waiting**: Wait for specific selectors, not arbitrary timeouts
3. **Incremental Capture**: Only capture pages that changed (compare with previous capture)
4. **Compression**: Optimize PNG screenshots for smaller file sizes

## Principles

### DO:
- Discover routes dynamically from project
- Wait for page content to fully load
- Capture full-page screenshots
- Generate navigable HTML reports
- Use parallel capture for speed
- Gracefully handle errors per-page

### DON'T:
- Hardcode route lists
- Capture before page is ready
- Skip pages on first error
- Block on MCP unavailability
- Capture duplicate routes