Add browser resolution support (width/height parameters)

[tzur-avn]

Add Browser Resolution Support (Width/Height Parameters)

🎯 Summary

Adds the ability to launch browsers with custom window dimensions via width and height parameters across all client APIs (Python, JavaScript, and MCP).

💡 Motivation

Users often need to test their applications at specific resolutions or take screenshots at precise dimensions. Currently, Vibium always launches browsers at the default size, making it difficult to:

• Test responsive designs at specific breakpoints
• Capture screenshots at standard resolutions (1080p, 4K, etc.)
• Automate testing across different viewport sizes
• Match specific device dimensions

✨ Changes

Go Clicker Binary

• Added Width and Height fields to LaunchOptions struct
• Passes --window-size=WIDTH,HEIGHT argument to Chrome
• Added --width and --height CLI flags to serve command
• Updated Router to forward dimensions to browser instances
• Updated MCP schema to support width/height parameters

Python Client

• Added optional width and height parameters to browser.launch() (async)
• Added optional width and height parameters to browser_sync.launch() (sync)
• Updated ClickerProcess.start() to pass flags to clicker binary
• Full docstrings with default values (1280x720)

JavaScript/TypeScript Client

• Extended LaunchOptions interface with width? and height?
• Updated async browser.launch() API
• Updated sync browserSync.launch() API
• Modified ClickerProcess to pass flags to clicker serve

Documentation & Examples

• Updated READMEs with usage examples
• Created example scripts for Python and JavaScript
• Added comprehensive test suite (11 test cases)

📝 Usage Examples

Python:

from vibium import browser_sync

# Launch at 1920x1080
vibe = browser_sync.launch(width=1920, height=1080)
vibe.go("https://example.com")
vibe.quit()

JavaScript:

import { browser } from 'vibium';

const vibe = await browser.launch({ width: 1920, height: 1080 });
await vibe.go('https://example.com');
await vibe.quit();

MCP (for AI agents):

{
  "tool": "browser_launch",
  "arguments": {
    "width": 1920,
    "height": 1080
  }
}

✅ Testing

Added comprehensive test suite covering:

• ✅ Default resolution (1280x720)
• ✅ Custom resolutions (800x600, 1920x1080, 2560x1440)
• ✅ Width-only parameter (uses default height)
• ✅ Height-only parameter (uses default width)
• ✅ Headless mode with custom resolution
• ✅ Both sync and async APIs
• ✅ Multiple sequential launches

All tests passing: 11/11 ✅

🔄 Backward Compatibility

Fully backward compatible - all parameters are optional with sensible defaults:

• Default width: 1280 pixels
• Default height: 720 pixels
• Existing code continues to work without any changes

📊 Files Changed

• Core: 7 files (Go clicker binary + proxy router)
• Python client: 3 files
• JavaScript client: 3 files
• Documentation: 4 files
• Tests: 2 new test files
• Examples: 2 example scripts

🧪 Verification

Integration tests (requires Chrome):

python3 clients/python/tests/test_resolution.py

📸 Screenshot Evidence

Screenshots captured at different resolutions show correct viewport sizing:

• 800x600: ~16KB
• 1280x720: ~16KB
• 1920x1080: ~20KB
• 2560x1440: ~20KB

🎨 Implementation Details

• Chrome receives --window-size argument directly
• Parameters flow: Client → ClickerProcess → clicker serve --width X --height Y → Router → Browser launcher → Chrome
• Type-safe across TypeScript/Python with proper annotations
• Validated with comprehensive error handling

📋 Checklist

• Code follows project style guidelines
• Added tests covering new functionality
• All tests passing (11/11)
• Updated documentation with examples
• Backward compatible (no breaking changes)
• Works across all clients (Python, JS, MCP)
• No new dependencies added

🤝 Reviewer Notes

This is a straightforward feature addition that enhances Vibium's flexibility without changing existing behavior. The implementation is consistent across all language clients and maintains the project's simple API design.

[hugs]

looks like this would fix/address #40 and #5, yes?

[tzur-avn]

Yes for 5
Most of 40