infinite-agents-public/DASHBOARD.md

# Dashboard Maintenance Guide

## Overview

The `index.html` dashboard automatically displays all demos in the project. It's designed to stay up-to-date with minimal effort.

## Quick Start

### View Dashboard
```bash
# Start server (if not running)
python3 -m http.server 8889

# Open in browser
firefox http://localhost:8889/
```

### Update Dashboard
```bash
# Regenerate after adding new demos
./generate_index.py

# Or make it executable and run directly
chmod +x generate_index.py
./generate_index.py
```

### Generate Screenshot Previews (NEW!)
```bash
# Install dependencies first (one time)
npm install

# Generate all screenshots
npm run screenshots

# Or generate by category
npm run screenshots:threejs
npm run screenshots:sdg
npm run screenshots:ui
```

## Auto-Update Strategies

### Option 1: Manual Regeneration (Simplest)

Run after generating new demos:
```bash
./generate_index.py
```

**Best for:** Occasional updates, full control

### Option 2: File Watcher (Development)

Auto-regenerate when files change:
```bash
# Install watcher (Ubuntu/Debian)
sudo apt install inotify-tools

# Start watcher
./watch_and_update.sh
```

**Best for:** Active development, instant updates

### Option 3: Git Hook (Automated)

Auto-regenerate before commits:
```bash
# Copy hook to git hooks directory
cp .githooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

**Best for:** Team workflows, version control

### Option 4: Integrate with Generation

Add to your infinite loop workflow:
```python
# After agent completion in infinite loop
python3 generate_index.py
```

**Best for:** Seamless workflow integration

## How It Works

### Generator Script (`generate_index.py`)

**What it does:**
1. Scans demo directories (`threejs_viz/`, `sdg_viz/`, `src/`, `src_infinite/`, `src_group/`)
2. Extracts titles and descriptions from HTML files
3. Updates the `demos` object in `index.html`
4. Updates category counts and statistics
5. Preserves all styling and functionality

**What it scans:**
- `threejs_viz/threejs_viz_*.html` → Three.js demos
- `sdg_viz/sdg_viz_*.html` → SDG network visualizations
- `d3_test/d3_viz_*.html` → D3 data visualizations
- `mapbox_test/mapbox_globe_*/index.html` → Mapbox globe visualizations
- `claude_code_devtools/claude_devtool_*.html` → Claude Code developer tools
- `src/ui_hybrid_*.html` → UI single-file components
- `src_infinite/ui_hybrid_*.html` → Infinite mode UI
- `src_group/ui_hybrid_*/index.html` → Modular UI components

**Current stats:** 107 demos across 7 categories

### File Structure

```
infinite-agents/
├── index.html                  # Dashboard (auto-generated data section)
├── generate_index.py           # Generator script
├── watch_and_update.sh         # File watcher script
├── DASHBOARD.md                # This guide
│
├── threejs_viz/                # Three.js demos
│   ├── threejs_viz_1.html
│   ├── threejs_viz_2.html
│   └── ...
│
├── sdg_viz/                    # SDG network demos
│   ├── sdg_viz_1.html
│   ├── sdg_viz_2.html
│   └── ...
│
├── d3_test/                    # D3 data visualizations
│   ├── d3_viz_1.html
│   ├── d3_viz_2.html
│   └── ...
│
├── mapbox_test/                # Mapbox globe visualizations
│   ├── mapbox_globe_1/
│   │   └── index.html
│   ├── mapbox_globe_2/
│   │   └── index.html
│   └── ...
│
├── claude_code_devtools/       # Claude Code developer tools
│   ├── claude_devtool_1.html
│   ├── claude_devtool_2.html
│   └── ...
│
├── src/                        # UI hybrid (single file)
│   ├── ui_hybrid_1.html
│   ├── ui_hybrid_2.html
│   └── ...
│
├── src_infinite/               # UI hybrid (infinite mode)
│   ├── ui_hybrid_1.html
│   ├── ui_hybrid_2.html
│   └── ...
│
└── src_group/                  # UI hybrid (modular)
    ├── ui_hybrid_1/
    │   └── index.html
    └── ...
```

## Customization

### Add New Demo Category

Edit `generate_index.py` and add scanning logic:

```python
def generate_demo_data():
    demos = {
        'threejs': [],
        'sdg': [],
        'uiSingle': [],
        'uiModular': [],
        'newCategory': []  # Add new category
    }

    # Add scanning for new category
    new_files = scan_directory('new_dir', 'pattern_*.html')
    for i, filepath in enumerate(new_files, 1):
        demos['newCategory'].append({
            'number': i,
            'title': extract_title_from_html(filepath),
            'description': extract_description_from_html(filepath),
            'path': filepath,
            'type': 'New Type',
            'techniques': []
        })

    return demos
```

Then update `index.html` template to add the category section.

### Modify Extraction Logic

Edit `extract_title_from_html()` or `extract_description_from_html()` in `generate_index.py`:

```python
def extract_title_from_html(filepath):
    """Customize how titles are extracted."""
    # Add custom regex patterns
    # Try different HTML elements
    # Handle edge cases
    pass
```

### Change Dashboard Styling

Edit `index.html` directly - the generator only updates the `demos` object and stats, preserving all styling.

## Workflow Integration

### After Manual Demo Creation

```bash
# 1. Create new demo
nano threejs_viz/threejs_viz_6.html

# 2. Regenerate dashboard
./generate_index.py

# 3. Refresh browser to see changes
```

### After Infinite Loop Generation

Add to your agent completion callback:

```python
# In your infinite loop orchestrator
def on_generation_complete():
    print("🔄 Updating dashboard...")
    subprocess.run(['python3', 'generate_index.py'])
    print("✅ Dashboard updated!")
```

### With Version Control

```bash
# 1. Generate new demos
./your_generation_command.sh

# 2. Update dashboard
./generate_index.py

# 3. Commit everything together
git add threejs_viz/ index.html
git commit -m "Add 5 new Three.js demos"
```

## Troubleshooting

### Dashboard shows old count

**Problem:** Statistics don't match actual files
**Solution:** Run `./generate_index.py` manually

### Can't execute script

**Problem:** Permission denied
**Solution:** `chmod +x generate_index.py watch_and_update.sh`

### Titles look wrong

**Problem:** Extraction isn't finding correct titles
**Solution:** Check HTML file structure, customize extraction in `generate_index.py`

### Watcher doesn't work

**Problem:** `inotifywait` command not found
**Solution:** Install with `sudo apt install inotify-tools`

### Server not accessible

**Problem:** Can't open http://localhost:8889/
**Solution:** Check if server is running: `python3 -m http.server 8889`

## Advanced Usage

### Generate JSON API

Export demo list as JSON for external tools:

```bash
# Add to generate_index.py
import json

demos = generate_demo_data()
with open('demos.json', 'w') as f:
    json.dump(demos, f, indent=2)
```

### Create Category Pages

Generate separate pages per category:

```bash
# Add to workflow
./generate_index.py --category threejs --output threejs.html
./generate_index.py --category sdg --output sdg.html
```

### Statistics Dashboard

Track growth over time:

```bash
# Log counts on each generation
./generate_index.py | tee -a dashboard_stats.log
```

## Best Practices

1. **Regenerate after bulk changes** - After generating multiple demos, run once instead of per-demo
2. **Use watcher during development** - Auto-update while actively creating
3. **Git hook for teams** - Ensure dashboard stays in sync across team
4. **Backup before customization** - Copy `index.html` before major changes
5. **Test extraction** - Verify titles/descriptions look good after adding new demo types

## Quick Reference

```bash
# Update dashboard
./generate_index.py

# Watch for changes
./watch_and_update.sh

# Start server
python3 -m http.server 8889

# View dashboard
firefox http://localhost:8889/

# Check status
find threejs_viz sdg_viz d3_test mapbox_test claude_code_devtools src src_infinite src_group -name "*.html" | wc -l
```

## Screenshot Preview System

### Overview

The dashboard now features a hybrid preview system combining:
- **Static screenshots** displayed in each demo card (fast, zero overhead)
- **Live iframe preview** on hover (interactive, full-featured)

This provides instant visual feedback while maintaining excellent performance.

### How It Works

1. **Screenshot Thumbnails**: Each card shows a 200px tall screenshot
2. **Hover to Preview**: Hover over any card for 800ms to see a live iframe preview
3. **Single Modal**: Only one iframe loads at a time (efficient memory usage)
4. **Fallback Display**: If screenshot is missing, shows placeholder icon

### Generating Screenshots

#### Initial Setup
```bash
# Install Node.js dependencies
npm install

# Install Playwright browsers
npx playwright install chromium
```

#### Generate All Screenshots
```bash
# Start server in one terminal
npm run server

# Generate screenshots in another terminal
npm run screenshots
```

This will capture screenshots for all 107 demos. Estimated time: ~5-8 minutes.

#### Generate by Category
```bash
# Only Three.js demos
npm run screenshots:threejs

# Only SDG network visualizations
npm run screenshots:sdg

# Only UI components
npm run screenshots:ui

# All categories available:
# - screenshots:threejs
# - screenshots:sdg
# - screenshots:d3
# - screenshots:mapbox
# - screenshots:devtools
# - screenshots:ui
```

#### Generate Single Screenshot
```bash
node generate_screenshots.js --single=threejs_viz/threejs_viz_1.html
```

### Screenshot Organization

```
infinite-agents/
├── screenshots/              # Auto-generated screenshots
│   ├── threejs_viz_threejs_viz_1.html.png
│   ├── sdg_viz_sdg_viz_1.html.png
│   ├── src_ui_hybrid_1.html.png
│   └── ...
└── generate_screenshots.js   # Screenshot generator script
```

Screenshot filenames follow the pattern: `path_to_file.html.png` with `/` replaced by `_`.

### Configuration

Edit `generate_screenshots.js` to customize:

```javascript
const DEMO_CATEGORIES = {
    threejs: {
        pattern: 'threejs_viz/threejs_viz_*.html',
        delay: 3000, // Wait time for WebGL rendering
    },
    // ... other categories
};
```

**Delay settings:**
- Three.js/Mapbox: 3000ms (WebGL needs time to render)
- D3/SDG: 1500-2000ms (SVG rendering + animations)
- UI Components: 800ms (static or simple animations)

### Troubleshooting Screenshots

#### Server not running
```bash
# Error: Server is not running!
# Solution: Start server first
python3 -m http.server 8889
```

#### Playwright not installed
```bash
# Error: Browser not found
# Solution: Install Playwright browsers
npx playwright install chromium
```

#### Missing screenshots
```bash
# Cards show 📸 placeholder
# Solution: Generate screenshots for that category
npm run screenshots:threejs  # or specific category
```

#### Update screenshots after changes
```bash
# After updating a demo, regenerate its screenshot
npm run screenshots  # Regenerate all
# or
node generate_screenshots.js --single=path/to/demo.html
```

### Workflow Integration

#### After Infinite Loop Generation
```bash
# 1. Generate new demos
/project:infinite-web specs/threejs_visualization_progressive.md threejs_viz 5

# 2. Update dashboard
./generate_index.py

# 3. Generate screenshots
npm run screenshots:threejs

# 4. Refresh browser to see new previews
```

#### Automated Workflow Script
```bash
#!/bin/bash
# update_dashboard.sh

echo "Updating dashboard..."
python3 generate_index.py

echo "Generating screenshots..."
npm run screenshots

echo "✅ Dashboard updated with previews!"
```

### Performance Metrics

**Before (No Previews):**
- Initial load: ~100KB
- Memory: ~50MB
- First paint: <100ms

**After (Screenshot Previews):**
- Initial load: ~2-3MB (all screenshots)
- Memory: ~80MB
- First paint: ~200ms
- Hover preview: +40MB per iframe (unloaded after close)

**With 107 Screenshots:**
- Total screenshot size: ~15-20MB (compressed PNGs)
- Browser caching: Screenshots cached after first load
- No performance impact on browsing (lazy loading)

## Future Enhancements

Potential improvements to consider:

- [x] Screenshot thumbnails for each demo ✅
- [x] Iframe preview on hover ✅
- [x] Automatically populate cards with screenshots ✅
- [x] Use Playwright for automated testing and evaluation of demos ✅
- [ ] WebP format for smaller screenshots (~40% reduction)
- [ ] Thumbnail optimization (reduced resolution for cards)
- [ ] Video preview for animated demos
- [ ] Demo tags and advanced filtering
- [ ] Screenshot diff detection (only regenerate changed demos)

---

**Last Updated:** October 10, 2025
**Current Version:** Dynamic auto-discovery with preview system
**Total Demos:** 107 (and counting!)
**Preview Features:** Screenshot thumbnails + Hover iframe preview