Documentation

# Launch with empty canvas (ignore saved state)
--empty

# Add devices to the main canvas
--device="iPhone 16 Pro"
--device="Galaxy S24"
--device="Desktop 1920x1080"

# Open device in a separate window
--detach="iPhone 15"

# Rotate device to landscape orientation
--rotate="iPhone 16 Pro"

# Multiple devices at once
--device="iPhone 16" --device="Pixel 9" --device="Galaxy S24"

# Load URL (https:// added automatically if no scheme)
--url=https://example.com
--url=example.com
--url=http://localhost:3000
--url=file:///path/to/index.html

# Set maximum zoom level (0.1 to 2.0, default: 0.5)
--zoom=0.8

# Enable synchronized scrolling for all devices
--scroll-sync

# Watch directory and auto-reload on changes
--watch-dir=/path/to/your/project

# Load a saved preset configuration
--preset=/path/to/my-preset.json

# Capture screenshot of a WebKit device
--webkit-view-screenshot-path=/path/to/output.png

# Capture screenshot of a CEF (Chromium) device
--cef-screenshot-path=/path/to/output.png

# Run test scroll on a device
--test-touch-scroll="iPhone 16 Pro"

# Log processed arguments to a file
--args-log-path=/path/to/args.log

# Write JSON layout metrics on each pass
--layout-log-path=/path/to/layout.json

# Launch with 3 devices, URL, synchronized scrolling, and file watching
BrowserView --empty \
  --device="iPhone 16 Pro" \
  --device="Galaxy S24" \
  --device="Desktop 1920x1080" \
  --url=http://localhost:3000 \
  --watch-dir=./src \
  --scroll-sync

import Foundation

DistributedNotificationCenter.default().post(
    name: NSNotification.Name("com.viewportstudio.addDevice"),
    object: "iPhone 16 Pro"
)

# Add a device
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.addDevice"), object: "iPhone 16 Pro"); RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))'

# Navigate to URL
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.navigateURL"), object: "https://example.com"); RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))'

# Open DevTools
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.openDevTools"), object: "Galaxy S24"); RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))'

import subprocess

def send_notification(name, value):
    script = f'''
    import Foundation
    DistributedNotificationCenter.default().post(
        name: NSNotification.Name("{name}"),
        object: "{value}"
    )
    RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))
    '''
    subprocess.run(['swift', '-e', script])

# Usage
send_notification('com.viewportstudio.addDevice', 'iPhone 16 Pro')
send_notification('com.viewportstudio.navigateURL', 'https://example.com')

const { execSync } = require('child_process');

function sendNotification(name, value) {
  const script = `
    import Foundation
    DistributedNotificationCenter.default().post(
        name: NSNotification.Name("${name}"),
        object: "${value}"
    )
    RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))
  `;
  execSync(`swift -e '${script}'`);
}

// Usage
sendNotification('com.viewportstudio.addDevice', 'iPhone 16 Pro');
sendNotification('com.viewportstudio.navigateURL', 'https://example.com');

#!/bin/bash
# Capture screenshots of a site on multiple devices

APP="/Applications/BrowserView.app/Contents/MacOS/BrowserView"

"$APP" --empty \
  --device="iPhone 16 Pro" \
  --device="Galaxy S24" \
  --device="Desktop 1920x1080" \
  --url="https://your-site.com" \
  --webkit-view-screenshot-path="./iphone.png" \
  --cef-screenshot-path="./android.png"

#!/bin/bash
# Automated demo: adding devices one by one with delays

BrowserView --empty --url="https://your-site.com" &
sleep 3

# Sequential device addition
for device in "iPhone 16 Pro" "Galaxy S24" "Desktop 1920x1080"; do
  swift -e "import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name(\"com.viewportstudio.addDevice\"), object: \"$device\"); RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))"
  sleep 2
done

# Opening DevTools for one device
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.openDevTools"), object: "Galaxy S24"); RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.1))'

# 1. Launch BrowserView with initial configuration
BrowserView --empty \
  --device="iPhone 16 Pro" \
  --url="http://localhost:3000" \
  --watch-dir=./src

# 2. Agent makes code changes...
# (App auto-reloads via watch-dir)

# 3. Agent adds more devices for testing
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.addDevice"), object: "Galaxy S24")'

# 4. Agent captures a screenshot for verification
# (Use CLI screenshot arguments or screen capture tools)

# 5. Agent opens DevTools for debugging
swift -e 'import Foundation; DistributedNotificationCenter.default().post(name: NSNotification.Name("com.viewportstudio.openDevTools"), object: "iPhone 16 Pro")'

# .github/workflows/visual-test.yml
name: Visual Regression Test
on: [push, pull_request]

jobs:
  visual-test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Start dev server
        run: npm run dev &

      - name: Wait for server
        run: sleep 5

      - name: Run BrowserView
        run: |
          "/Applications/BrowserView.app/Contents/MacOS/BrowserView" \
            --empty \
            --device="iPhone 16 Pro" \
            --device="Desktop 1920x1080" \
            --url="http://localhost:3000" \
            --webkit-view-screenshot-path="./screenshots/iphone.png" \
            --cef-screenshot-path="./screenshots/desktop.png" \
            --layout-log-path="./layout.json"

      - name: Upload screenshots
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: screenshots/

#!/bin/bash
# visual-regression.sh — visual regression testing

set -e
APP="/Applications/BrowserView.app/Contents/MacOS/BrowserView"
SCREENSHOTS_DIR="./screenshots"
mkdir -p "$SCREENSHOTS_DIR"

# Start dev server
npm run dev &
DEV_PID=$!
sleep 5

# Capture screenshots
"$APP" --empty \
  --device="iPhone 16 Pro" \
  --device="Desktop 1920x1080" \
  --url="http://localhost:3000" \
  --webkit-view-screenshot-path="$SCREENSHOTS_DIR/iphone.png" \
  --cef-screenshot-path="$SCREENSHOTS_DIR/desktop.png" \
  --layout-log-path="$SCREENSHOTS_DIR/layout.json"

# Stop dev server
kill $DEV_PID

echo "✅ Screenshots saved to $SCREENSHOTS_DIR"

# fastlane/Fastfile
lane :visual_test do
  sh("npm run dev &")
  sleep(5)

  viewport_app = "/Applications/BrowserView.app/Contents/MacOS/BrowserView"

  sh("#{viewport_app} --empty " \
     "--device='iPhone 16 Pro' " \
     "--device='Desktop 1920x1080' " \
     "--url='http://localhost:3000' " \
     "--webkit-view-screenshot-path='./screenshots/iphone.png' " \
     "--cef-screenshot-path='./screenshots/desktop.png'")

  sh("pkill -f 'npm run dev' || true")
end

{
  "timestamp": "2025-01-15T10:30:00Z",
  "devices": [
    {
      "name": "iPhone 16 Pro",
      "engine": "webkit",
      "width": 393,
      "height": 852,
      "scale": 3,
      "rotated": false,
      "position": { "x": 0, "y": 0 }
    },
    {
      "name": "Desktop 1920x1080",
      "engine": "cef",
      "width": 1920,
      "height": 1080,
      "scale": 1,
      "rotated": false,
      "position": { "x": 420, "y": 0 }
    }
  ],
  "canvas": {
    "zoom": 0.5,
    "scrollSync": true
  }
}

#!/bin/bash
# Verify that all devices loaded correctly

LAYOUT=$(cat layout.json)

# Check device count
DEVICE_COUNT=$(echo "$LAYOUT" | python3 -c "import sys,json; print(len(json.load(sys.stdin)['devices']))")

if [ "$DEVICE_COUNT" -ne 3 ]; then
  echo "❌ Expected 3 devices, got $DEVICE_COUNT"
  exit 1
fi

echo "✅ Layout log: $DEVICE_COUNT devices loaded"

# Python: parse layout log
import json

with open('layout.json') as f:
    layout = json.load(f)

for device in layout['devices']:
    print(f"{device['name']}: {device['width']}x{device['height']} ({device['engine']})")

# Verify all devices are present
expected = {"iPhone 16 Pro", "Galaxy S24", "Desktop 1920x1080"}
actual = {d['name'] for d in layout['devices']}
assert expected == actual, f"Missing devices: {expected - actual}"

# Make sure you're using the full path to the executable:
"/Applications/BrowserView.app/Contents/MacOS/BrowserView" --empty --device="iPhone 16 Pro"

# Or add an alias to ~/.zshrc:
alias viewport='"/Applications/BrowserView.app/Contents/MacOS/BrowserView"'

# For argument debugging, use the log:
BrowserView --args-log-path=/tmp/viewport-args.log --device="iPhone 16 Pro"
cat /tmp/viewport-args.log

# Check that the application is running:
pgrep -f "BrowserView" || echo "Application is not running!"

# Make sure RunLoop has time to send the notification:
swift -e '
import Foundation
DistributedNotificationCenter.default().post(
    name: NSNotification.Name("com.viewportstudio.addDevice"),
    object: "iPhone 16 Pro"
)
RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.5))
'
# Note: a 0.5s delay (instead of 0.1s) may help with unstable delivery