Initial commit

skills/benchmarking/html-to-png-converter/reference/playwright-cli.md

@@ -0,0 +1,109 @@
+# Playwright CLI Reference
+
+## Screenshot Command
+
+```bash
+playwright screenshot [options] <url> <output>
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--full-page` | Capture full scrollable page | Off (viewport only) |
+| `--viewport-size=WxH` | Set viewport size | 800x600 |
+| `--scale=N` | Device scale factor | 1 |
+| `--wait-for-timeout=ms` | Wait before screenshot | 0 |
+| `--wait-for-selector=sel` | Wait for element | None |
+| `--color-scheme=mode` | `light` or `dark` | System |
+| `--device=name` | Emulate device | None |
+| `--timeout=ms` | Navigation timeout | 30000 |
+| `--browser=name` | Browser to use | chromium |
+
+## Browser Options
+
+```bash
+# Use specific browser
+playwright screenshot --browser=firefox "file://$(pwd)/diagram.html" output.png
+playwright screenshot --browser=webkit "file://$(pwd)/diagram.html" output.png
+playwright screenshot --browser=chromium "file://$(pwd)/diagram.html" output.png
+```
+
+## Device Emulation
+
+```bash
+# Emulate specific device
+playwright screenshot --device="iPhone 12" "file://$(pwd)/diagram.html" output.png
+playwright screenshot --device="iPad Pro" "file://$(pwd)/diagram.html" output.png
+```
+
+List all devices:
+```bash
+playwright devices
+```
+
+## Examples
+
+### Basic Full Page
+
+```bash
+playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+### High Resolution (2x)
+
+```bash
+playwright screenshot --full-page --scale=2 "file://$(pwd)/diagram.html" output@2x.png
+```
+
+### Dark Mode
+
+```bash
+playwright screenshot --full-page --color-scheme=dark "file://$(pwd)/diagram.html" dark.png
+```
+
+### Custom Viewport
+
+```bash
+playwright screenshot --viewport-size=1920x1080 "file://$(pwd)/diagram.html" output.png
+```
+
+### Wait for Content
+
+```bash
+# Wait 2 seconds for dynamic content
+playwright screenshot --full-page --wait-for-timeout=2000 "file://$(pwd)/diagram.html" output.png
+
+# Wait for specific element
+playwright screenshot --full-page --wait-for-selector=".loaded" "file://$(pwd)/diagram.html" output.png
+```
+
+## PDF Generation (Alternative)
+
+For PDF output instead of PNG:
+
+```bash
+playwright pdf "file://$(pwd)/document.html" output.pdf
+```
+
+PDF-specific options:
+- `--format=Letter|A4|...`
+- `--landscape`
+- `--margin=top,right,bottom,left`
+- `--print-background`
+
+## Installation Commands
+
+```bash
+# Install Playwright
+npm install -g playwright
+
+# Install browsers
+playwright install              # All browsers
+playwright install chromium     # Chromium only
+playwright install firefox      # Firefox only
+playwright install webkit       # WebKit only
+
+# Check version
+playwright --version
+```

skills/benchmarking/html-to-png-converter/reference/troubleshooting.md

@@ -0,0 +1,144 @@
+# Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### "Browser not found" / "Executable doesn't exist"
+
+**Cause**: Playwright browsers not installed.
+
+**Solution**:
+```bash
+# Install browsers
+playwright install chromium
+
+# Or install all browsers
+playwright install
+```
+
+### "Command not found: playwright"
+
+**Cause**: Playwright not installed globally.
+
+**Solutions**:
+```bash
+# Option 1: Install globally
+npm install -g playwright
+
+# Option 2: Use via npx (no install needed)
+npx playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+### Blank or White Image
+
+**Cause**: File path not resolving correctly.
+
+**Debug**:
+```bash
+# Check the file exists
+ls -la diagram.html
+
+# Check URL format (should be file://...)
+echo "file://$(pwd)/diagram.html"
+```
+
+**Solution**: Ensure using `file://` protocol with absolute path.
+
+### Image is 800x600 (Viewport Only)
+
+**Cause**: Missing `--full-page` flag.
+
+**Solution**:
+```bash
+# Add --full-page flag
+playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+### Missing Images/CSS in Output
+
+**Cause**: HTML uses relative paths that don't resolve in file:// context.
+
+**Solutions**:
+
+1. **Use absolute paths in HTML**:
+```html
+<!-- Instead of -->
+<img src="images/logo.png">
+<!-- Use -->
+<img src="file:///Users/you/project/images/logo.png">
+```
+
+2. **Embed images as base64**:
+```html
+<img src="data:image/png;base64,iVBORw0KGgoAAAANS...">
+```
+
+3. **Inline CSS**:
+```html
+<style>
+  /* CSS inline instead of <link> */
+</style>
+```
+
+### Fonts Not Rendering
+
+**Cause**: Web fonts not loading in file:// context.
+
+**Solutions**:
+
+1. Use system fonts:
+```css
+font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+```
+
+2. Embed fonts as base64 in CSS.
+
+### Slow Conversion
+
+**Cause**: Browser startup overhead or large content.
+
+**Solutions**:
+```bash
+# For batch operations, reuse browser (requires script)
+# For single operations, ~3-5 seconds is normal
+
+# If content is dynamic, reduce wait time
+playwright screenshot --full-page --wait-for-timeout=500 "file://$(pwd)/diagram.html" output.png
+```
+
+### Permission Denied
+
+**Cause**: Cannot write to output directory.
+
+**Solution**:
+```bash
+# Check directory permissions
+ls -la $(dirname output.png)
+
+# Create directory if needed
+mkdir -p docs/images
+```
+
+### Fuzzy/Blurry Text
+
+**Cause**: Low DPI capture.
+
+**Solution**:
+```bash
+# Use 2x scale for retina-quality output
+playwright screenshot --full-page --scale=2 "file://$(pwd)/diagram.html" output.png
+```
+
+## Debug Mode
+
+For detailed troubleshooting:
+
+```bash
+# Enable debug output
+DEBUG=pw:api playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+## Getting Help
+
+1. Check Playwright docs: https://playwright.dev/docs/cli
+2. Verify HTML renders in browser: `open diagram.html`
+3. Test with simple HTML first to isolate issue