webshot/README.md

# 📸 WebShot

> Shoot your favorite Websites!!!

A beautiful CLI tool for capturing screenshots, videos, and complete HTML snapshots of websites using Puppeteer. Features an interactive "shoot mode" with a pastel-themed terminal UI.

```
╦ ╦╔═╗╔╗ ╔═╗╦ ╦╔═╗╔╦╗
║║║║╣ ╠╩╗╚═╗╠═╣║ ║ ║
╚╩╝╚═╝╚═╝╚═╝╩ ╩╚═╝ ╩

Shoot your favorite Websites!!!
────────────────────────────────
```

## ✨ Features

- 📷 **Multiple export formats**: PNG, JPG, WEBP, PDF, MP4/WebM video, HTML with assets
- 🎯 **Interactive shoot mode**: Press spacebar when ready or wait for countdown
- 🎨 **Beautiful terminal UI**: Pastel-colored spinners and progress indicators
- 📜 **Custom automation scripts**: Execute Puppeteer code before capture
- 🐛 **Debug mode**: Built-in Node.js inspector support
- ⚡ **Fast video recording**: Efficient screenshot-loop method with ffmpeg
- 🌐 **Complete HTML snapshots**: Download websites with all assets
- 📱 **Flexible viewports**: Custom dimensions or mobile presets

## 🚀 Installation

```bash
# Clone or download the repository
git clone <your-repo-url>
cd webshot

# Install dependencies
pnpm install

# Make executable (if needed)
chmod +x webshot

# Optional: Link globally to use from anywhere
npm link
# or add to your PATH
```

### Requirements

- **Node.js** (v14 or higher recommended)
- **ffmpeg** (required for MP4/WebM video recording)
  ```bash
  # Debian/Ubuntu
  sudo apt install ffmpeg

  # macOS
  brew install ffmpeg
  ```

## 📖 Usage

### Basic Commands

```bash
# Interactive screenshot with shoot mode
webshot -u https://github.com

# Quick screenshot without delay
webshot -u https://example.com --no-delay

# Specify output path
webshot -u https://example.com -o screenshots/github.png
```

### Export Formats

#### PNG (default)
```bash
webshot -u https://example.com -f png
```

#### JPEG with quality control
```bash
webshot -u https://example.com -f jpg --quality 95
```

#### WEBP for smaller file sizes
```bash
webshot -u https://example.com -f webp --quality 90
```

#### PDF documents
```bash
webshot -u https://github.com/features -f pdf
```

#### MP4 video recording
```bash
# 10 second video at 30 FPS
webshot -u https://bruno-simon.com -f mp4 --duration 10000 --fps 30

# WebM format (VP9 codec)
webshot -u https://bruno-simon.com -f mp4 -o output.webm --duration 5000
```

#### Complete HTML with assets
```bash
# Downloads all images, CSS, JS to assets/ subdirectory
webshot -u https://stripe.com -f html -o stripe/index.html
```

### Custom Automation Scripts

Execute custom Puppeteer code before capturing:

```bash
# Use a built-in example
webshot -u https://example.com -s examples/dark-mode.js

# Chain multiple behaviors
webshot -u https://example.com -s examples/scroll-animation.js -f mp4 --duration 8000
```

**Available example scripts:**
- `scroll-animation.js` - Scroll to bottom and back to top
- `dark-mode.js` - Attempt to enable dark mode
- `interact-form.js` - Fill out forms with demo data
- `hover-effects.js` - Simulate hover states
- `mobile-view.js` - Switch to mobile viewport
- `animated-sections.js` - Trigger scroll-based animations

**Create your own script:**
```javascript
// my-script.js
console.log('🎬 Running custom automation...');

// You have access to the 'page' object
await page.evaluate(() => {
  document.body.style.backgroundColor = '#ff69b4';
});

await new Promise(resolve => setTimeout(resolve, 1000));
console.log('✓ Done!');
```

### Viewport Configuration

```bash
# Custom dimensions
webshot -u https://example.com -w 1280 -h 720

# Mobile viewport (use with script)
webshot -u https://example.com -s examples/mobile-view.js
```

### Custom Shoot Delay

```bash
# 5 second delay
webshot -u https://example.com 5000

# 10 second delay
webshot -u https://example.com 10000
```

### Debug Mode

```bash
# Enable debug logging and Node.js inspector
webshot -u https://example.com --debug

# Connect to chrome://inspect in Chrome DevTools
# or use: node inspect localhost:9229

# Custom debug port
DEBUG_PORT=9230 webshot -u https://example.com --debug

# Debug slow or complex websites
webshot -u https://heavy-site.com --debug --wait-until load --timeout 60000
```

## 🎯 Wait Strategies

Control when navigation is considered complete:

```bash
# Wait for window.load event (fastest)
webshot -u https://example.com --wait-until load

# Wait for DOM ready
webshot -u https://example.com --wait-until domcontentloaded

# Wait for network to be mostly idle (default, best for most sites)
webshot -u https://example.com --wait-until networkidle2

# Wait for complete network silence (slowest, most complete)
webshot -u https://example.com --wait-until networkidle0

# Increase timeout for slow sites
webshot -u https://slow-site.com --timeout 60000
```

## 📋 Command Reference

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `-u, --url <url>` | Target URL to capture | *required* |
| `-f, --format <format>` | Export format: `png`, `jpg`, `webp`, `pdf`, `mp4`, `html` | `png` |
| `-o, --output <path>` | Output file path | `<hostname>-<timestamp>.<format>` |
| `-s, --script <path>` | Custom Puppeteer automation script | - |
| `-w, --width <px>` | Viewport width | `1920` |
| `-h, --height <px>` | Viewport height | `1080` |
| `--no-delay` | Skip interactive shoot delay | `false` |
| `--full-page` | Capture full page (scrollable content) | `true` |
| `--quality <1-100>` | Image quality for JPG/WEBP | `90` |
| `--duration <ms>` | Video duration for MP4 | `5000` |
| `--fps <fps>` | Video FPS for MP4 | `30` |
| `--wait-until <state>` | Page load state: `load`, `domcontentloaded`, `networkidle0`, `networkidle2` | `networkidle2` |
| `--timeout <ms>` | Navigation timeout | `30000` |
| `--debug` | Enable debug mode with Node.js inspector | `false` |
| `--help` | Show help message | - |

### Arguments

| Argument | Description | Default |
|----------|-------------|---------|
| `[delay]` | Shoot delay in milliseconds | `3000` |

## 🌐 Cool Websites to Try

```bash
# 3D interactive portfolio
webshot -u https://bruno-simon.com -f mp4 --duration 10000

# WebGL demos and examples
webshot -u https://threejs.org/examples -f webp

# Beautiful modern design
webshot -u https://stripe.com -f pdf

# Modern UI with animations
webshot -u https://linear.app -f png
```

## 🎨 Terminal UI

WebShot features a beautiful pastel-themed terminal interface:

- **Animated spinners** with rotating frames (◐ ◓ ◑ ◒)
- **Progress bars** for video rendering
- **Color-coded output** using pastel colors (mint, sky, lavender, peach, coral)
- **Interactive countdown** with spacebar to shoot
- **File overwrite prompts** to prevent accidents

## 🔧 How It Works

### Screenshot Capture
1. Launches headless Chromium via Puppeteer
2. Sets viewport and navigates to URL
3. Waits for fonts and network activity
4. Executes custom script (if provided)
5. Shows interactive shoot mode countdown
6. Captures screenshot using Puppeteer's `page.screenshot()`

### Video Recording
1. Creates temporary frames directory
2. Captures JPEG screenshots in a fast loop
3. Writes frames to disk with sequential naming
4. Uses ffmpeg to convert frames to video:
   - **MP4**: H.264 codec with `-preset fast -crf 23`
   - **WebM**: VP9 codec with `-crf 30`
5. Duplicates frames to reach target FPS
6. Cleans up temporary frames

### HTML Export
1. Extracts all resource URLs (images, CSS, JS, favicon)
2. Downloads each resource using Puppeteer
3. Saves to `assets/` subdirectory
4. Rewrites HTML to use local paths
5. Returns to original page

## 📦 Package Details

- **Name**: `@valknarness/webshot`
- **Version**: 1.0.0
- **Main**: Single-file executable (`webshot`)
- **Dependencies**: `puppeteer@^24.26.0`
- **License**: MIT
- **Author**: valknar@pivoine.art

## 🤝 Contributing

This is a personal project, but suggestions and improvements are welcome!

## 📄 License

MIT License - feel free to use and modify as needed.

## ⚠️ Security Notes

- Custom scripts are executed with `eval()` and have full access to Node.js APIs
- Only use trusted scripts from reliable sources
- Be cautious when capturing websites with sensitive information
- Video recording creates temporary files that are cleaned up automatically

## 🐛 Troubleshooting

### ffmpeg not found
```bash
# Install ffmpeg
sudo apt install ffmpeg  # Debian/Ubuntu
brew install ffmpeg      # macOS
```

### Puppeteer installation issues
```bash
# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### Timeout errors on slow sites
```bash
# Increase timeout and use faster wait strategy
webshot -u https://slow-site.com --timeout 60000 --wait-until load
```

### Video recording too slow
```bash
# Reduce FPS or duration
webshot -u https://example.com -f mp4 --fps 24 --duration 3000
```

### Debug complex issues
```bash
# Enable debug mode to see detailed logs
webshot -u https://example.com --debug
```

## 💡 Tips

- Use `--no-delay` in scripts and automation
- WebP format offers the best quality-to-size ratio for screenshots
- For video recording, 30 FPS is smooth for most content
- Use `networkidle2` (default) for most sites, `load` for fast captures
- Mobile viewport scripts work best with responsive websites
- HTML export is great for offline archiving or analysis
- Debug mode shows all network requests and page console output

---

**Made with 💜 by valknar**