Initial commit

skills/benchmarking/html-to-png-converter/workflow/phase-1-prerequisites.md

@@ -0,0 +1,53 @@
+# Phase 1: Prerequisites Check
+
+## Overview
+
+Before converting HTML to PNG, verify Playwright is installed and browsers are available.
+
+## Steps
+
+### 1.1 Check Playwright Installation
+
+```bash
+# Check if playwright is available
+playwright --version
+```
+
+**If not found**:
+```bash
+# Install globally
+npm install -g playwright
+
+# Or use via npx (no global install)
+npx playwright --version
+```
+
+### 1.2 Install Browsers
+
+```bash
+# Install all browsers
+playwright install
+
+# Or just Chromium (smallest, ~150MB)
+playwright install chromium
+```
+
+### 1.3 Verify Setup
+
+```bash
+# Quick test - should create a PNG of example.com
+playwright screenshot https://example.com test.png && rm test.png
+echo "Playwright setup verified!"
+```
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| `command not found: playwright` | `npm install -g playwright` or use `npx playwright` |
+| Browser not found | Run `playwright install chromium` |
+| Permission denied | Use `sudo npm install -g playwright` or fix npm permissions |
+
+## Next Phase
+
+Once prerequisites are verified, proceed to **Phase 2: Path Resolution**.

skills/benchmarking/html-to-png-converter/workflow/phase-2-paths.md

@@ -0,0 +1,67 @@
+# Phase 2: Path Resolution
+
+## Overview
+
+Playwright's screenshot command requires properly formatted `file://` URLs. This phase covers path construction patterns.
+
+## URL Format
+
+Playwright requires URLs, not bare file paths:
+
+```
+file:// + absolute_path = valid URL
+```
+
+## Path Patterns
+
+### From Current Directory
+
+```bash
+# Using $(pwd) for absolute path
+playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+### From Absolute Path
+
+```bash
+# Direct absolute path
+playwright screenshot --full-page "file:///Users/connor/project/diagram.html" output.png
+```
+
+### Handling Spaces in Paths
+
+```bash
+# Quote the entire URL
+playwright screenshot --full-page "file://$(pwd)/my diagram.html" output.png
+```
+
+### Relative to Project Root
+
+```bash
+# Navigate from any subdirectory
+playwright screenshot --full-page "file://$(git rev-parse --show-toplevel)/docs/diagram.html" output.png
+```
+
+## Path Validation
+
+Before running conversion, verify the file exists:
+
+```bash
+# Check file exists
+test -f "diagram.html" && echo "File found" || echo "File not found"
+
+# List HTML files in current directory
+ls -la *.html
+```
+
+## Anti-Patterns
+
+| Wrong | Correct |
+|-------|---------|
+| `playwright screenshot diagram.html` | `playwright screenshot "file://$(pwd)/diagram.html"` |
+| `playwright screenshot ./diagram.html` | `playwright screenshot "file://$(pwd)/diagram.html"` |
+| `playwright screenshot file:diagram.html` | `playwright screenshot "file://$(pwd)/diagram.html"` |
+
+## Next Phase
+
+Once path is resolved, proceed to **Phase 3: Screenshot Capture**.

skills/benchmarking/html-to-png-converter/workflow/phase-3-capture.md

@@ -0,0 +1,71 @@
+# Phase 3: Screenshot Capture
+
+## Overview
+
+Execute the Playwright screenshot command with appropriate options for your use case.
+
+## Basic Command
+
+```bash
+playwright screenshot --full-page "file://$(pwd)/diagram.html" output.png
+```
+
+## Command Options
+
+| Option | Purpose | Example |
+|--------|---------|---------|
+| `--full-page` | Capture entire document | Required for most diagrams |
+| `--viewport-size=WxH` | Set initial viewport | `--viewport-size=1920x1080` |
+| `--wait-for-timeout=ms` | Wait before capture | `--wait-for-timeout=1000` |
+| `--device=name` | Emulate device | `--device="iPhone 12"` |
+| `--color-scheme=mode` | Light/dark mode | `--color-scheme=dark` |
+
+## Common Patterns
+
+### Academic Diagrams (Most Common)
+
+```bash
+# Full page capture - lets content determine size
+playwright screenshot --full-page "file://$(pwd)/docs/architecture.html" docs/architecture.png
+```
+
+### Fixed Width Output
+
+```bash
+# Set specific width, full page height
+playwright screenshot --full-page --viewport-size=1200x800 "file://$(pwd)/diagram.html" output.png
+```
+
+### Wait for Dynamic Content
+
+```bash
+# Wait 2 seconds for animations/rendering
+playwright screenshot --full-page --wait-for-timeout=2000 "file://$(pwd)/diagram.html" output.png
+```
+
+### Dark Mode Diagram
+
+```bash
+playwright screenshot --full-page --color-scheme=dark "file://$(pwd)/diagram.html" output-dark.png
+```
+
+## Batch Conversion
+
+```bash
+# Convert all HTML files in docs/ to PNG
+for f in docs/*.html; do
+  output="${f%.html}.png"
+  playwright screenshot --full-page "file://$(pwd)/$f" "$output"
+  echo "Converted: $f -> $output"
+done
+```
+
+## Output Location
+
+- **Same directory**: Just use filename (`output.png`)
+- **Different directory**: Use path (`docs/images/output.png`)
+- **Ensure directory exists**: `mkdir -p docs/images` before running
+
+## Next Phase
+
+Proceed to **Phase 4: Output Verification** to validate the result.

skills/benchmarking/html-to-png-converter/workflow/phase-4-verification.md

@@ -0,0 +1,84 @@
+# Phase 4: Output Verification
+
+## Overview
+
+After conversion, verify the PNG was created correctly with expected dimensions and content.
+
+## Verification Steps
+
+### 4.1 Check File Exists
+
+```bash
+# Verify file was created
+test -f output.png && echo "PNG created successfully" || echo "ERROR: PNG not found"
+```
+
+### 4.2 Check File Size
+
+```bash
+# Non-zero file size indicates content
+ls -lh output.png
+
+# If file is very small (<1KB), something may be wrong
+```
+
+### 4.3 Check Dimensions (macOS)
+
+```bash
+# Using sips (built into macOS)
+sips -g pixelHeight -g pixelWidth output.png
+```
+
+**Expected output**:
+```
+  pixelHeight: 1200
+  pixelWidth: 800
+```
+
+**Warning signs**:
+- 800x600 = viewport-only capture (missing `--full-page`)
+- Very small dimensions = content not rendering
+
+### 4.4 Visual Inspection
+
+```bash
+# Open in default image viewer (macOS)
+open output.png
+
+# Or in Preview specifically
+open -a Preview output.png
+```
+
+## Common Issues and Fixes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 800x600 dimensions | No `--full-page` | Add `--full-page` flag |
+| Blank/white image | Wrong file path | Check `file://` URL |
+| Missing images | Relative paths in HTML | Use absolute paths or embed base64 |
+| Cut off content | Viewport too small | Use `--full-page` or increase viewport |
+| Fuzzy text | Low DPI | Add `--scale=2` for retina |
+
+## Quality Checks
+
+- [ ] File exists and has reasonable size (>10KB for diagrams)
+- [ ] Dimensions match content (not 800x600)
+- [ ] All visual elements rendered (text, colors, borders)
+- [ ] No blank areas or missing components
+- [ ] Text is readable and sharp
+
+## Retina/High-DPI Output
+
+For sharper images (publications):
+
+```bash
+# 2x scale for retina
+playwright screenshot --full-page --scale=2 "file://$(pwd)/diagram.html" diagram@2x.png
+```
+
+## Cleanup
+
+```bash
+# Remove test files if any
+rm -f test.png
+```