@matware/e2e-runner 1.3.1 → 1.5.0

package/src/pool.js

@@ -4,9 +4,13 @@
  * Connectivity to browser pools and Docker Compose lifecycle.
  * Supports multiple pool drivers:
  *   - "browserless" — browserless/chrome with /pressure and /sessions HTTP API
- *   - "cdp"         — generic CDP pool (Lightpanda, raw Chrome, etc.) using /json/version health check
+ *   - "cdp"         — generic CDP pool (raw Chrome, etc.) using /json/version health check
+ *   - "lightpanda"  — Lightpanda browser (Zig-based, 9x faster, ~16x less memory) via CDP on port 9222
+ *   - "obscura"     — Obscura headless browser (Rust+V8, ~30 MB, anti-detect) via CDP on port 9222
  *   - "steel"       — Steel Browser with /v1/sessions REST API and session lifecycle
- *   - "auto"        — detect driver by probing endpoints: /pressure → browserless, /v1/sessions → steel, fallback → cdp
+ *   - "auto"        — detect driver by probing endpoints: /pressure → browserless, /v1/sessions → steel,
+ *                     /json/version with Browser=lightpanda → lightpanda, Browser=obscura → obscura,
+ *                     fallback → cdp
  */
 
 import puppeteer from 'puppeteer-core';
@@ -25,12 +29,25 @@ function sleep(ms) {
 
 // ── Driver detection cache ────────────────────────────────────────────────────
 
+/** Set of driver identifiers accepted by config, test JSON, and CLI overrides. */
+export const KNOWN_DRIVERS = new Set(['auto', 'browserless', 'cdp', 'lightpanda', 'obscura', 'steel']);
+
 /** Caches detected driver per pool URL to avoid re-probing on every status call. */
 const driverCache = new Map();
 
+/**
+ * Caches the canonical Puppeteer WS endpoint per pool URL, as advertised
+ * by /json/version → webSocketDebuggerUrl. Used by connectToPool so users
+ * can configure either http://host:port or ws://host:port for obscura,
+ * lightpanda, and generic cdp pools without needing to know the
+ * /devtools/browser suffix Obscura requires.
+ */
+const wsEndpointCache = new Map();
+
 /** Clears the driver cache (useful for tests or pool restarts). */
 export function clearDriverCache() {
   driverCache.clear();
+  wsEndpointCache.clear();
 }
 
 /** Returns the cached driver for a pool URL, or null if not yet detected. */
@@ -38,9 +55,16 @@ export function getCachedDriver(poolUrl) {
   return driverCache.get(poolUrl) || null;
 }
 
+/** Returns the cached webSocketDebuggerUrl for a pool URL, or null. */
+export function getCachedWsEndpoint(poolUrl) {
+  return wsEndpointCache.get(poolUrl) || null;
+}
+
 /**
  * Detects the pool driver by probing HTTP endpoints.
- * Probe order: /pressure (browserless) → /v1/sessions (steel) → fallback (cdp).
+ * Probe order: /pressure (browserless) → /v1/sessions (steel) →
+ *              /json/version with Browser=lightpanda → lightpanda, Browser=obscura → obscura,
+ *              fallback → cdp.
  */
 async function detectPoolDriver(poolUrl) {
   if (driverCache.has(poolUrl)) return driverCache.get(poolUrl);
@@ -71,18 +95,89 @@ async function detectPoolDriver(poolUrl) {
     }
   } catch { /* not steel */ }
 
-  // Fallback: generic CDP
+  // Probe Lightpanda / Obscura / generic CDP: /json/version
+  // Capture webSocketDebuggerUrl so connectToPool can use the canonical
+  // ws:// endpoint regardless of how the user spelled poolUrl.
+  try {
+    const res = await fetch(`${httpUrl}/json/version`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const data = await res.json();
+      if (typeof data.webSocketDebuggerUrl === 'string' && data.webSocketDebuggerUrl) {
+        wsEndpointCache.set(poolUrl, rewriteWsHost(data.webSocketDebuggerUrl, poolUrl));
+      }
+      const browser = typeof data.Browser === 'string' ? data.Browser.toLowerCase() : '';
+      if (browser.includes('lightpanda')) {
+        driverCache.set(poolUrl, 'lightpanda');
+        return 'lightpanda';
+      }
+      if (browser.includes('obscura')) {
+        driverCache.set(poolUrl, 'obscura');
+        return 'obscura';
+      }
+      // /json/version answered with a Browser field but it isn't one we
+      // specifically recognize — treat as generic CDP.
+      driverCache.set(poolUrl, 'cdp');
+      return 'cdp';
+    }
+  } catch { /* not CDP-family or network error */ }
+
+  // Fallback: generic CDP (assume ws:// endpoint as-is)
   driverCache.set(poolUrl, 'cdp');
   return 'cdp';
 }
 
+/**
+ * Some CDP servers (notably Obscura when bound to 0.0.0.0) advertise an
+ * internal host in webSocketDebuggerUrl that does not match the URL the
+ * client used. Rewrite host:port to match the original poolUrl so the
+ * resulting ws:// is reachable from this machine.
+ */
+function rewriteWsHost(wsUrl, poolUrl) {
+  try {
+    const ws = new URL(wsUrl);
+    const ref = new URL(poolUrl.replace(/^ws/, 'http'));
+    ws.hostname = ref.hostname;
+    if (ref.port) ws.port = ref.port;
+    return ws.toString();
+  } catch {
+    return wsUrl;
+  }
+}
+
+/**
+ * Returns a Puppeteer-ready ws:// endpoint for a CDP-family pool URL.
+ * Uses the cache when available; otherwise probes /json/version on demand.
+ * Falls back to coercing the input http://→ws:// if discovery fails.
+ */
+async function resolveCdpWsEndpoint(poolUrl) {
+  const cached = wsEndpointCache.get(poolUrl);
+  if (cached) return cached;
+
+  const httpUrl = poolUrl.replace(/^ws:/, 'http:').replace(/^wss:/, 'https:');
+  try {
+    const res = await fetch(`${httpUrl}/json/version`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const data = await res.json();
+      if (typeof data.webSocketDebuggerUrl === 'string' && data.webSocketDebuggerUrl) {
+        const ws = rewriteWsHost(data.webSocketDebuggerUrl, poolUrl);
+        wsEndpointCache.set(poolUrl, ws);
+        return ws;
+      }
+    }
+  } catch { /* fall through to coercion */ }
+
+  // No discovery — assume the input is already a usable ws endpoint.
+  return poolUrl.replace(/^http:/, 'ws:').replace(/^https:/, 'wss:');
+}
+
 /**
  * Resolves the effective driver string.
- * Maps config values: 'auto' → detect, 'lightpanda' → 'cdp', explicit → pass through.
+ * Maps config values: 'auto' → detect, explicit → cache and pass through.
  */
 async function resolveDriver(poolUrl, poolDriver) {
   if (!poolDriver || poolDriver === 'auto') return detectPoolDriver(poolUrl);
-  if (poolDriver === 'lightpanda') return 'cdp';
+  // Cache explicit driver so status calls and connect calls share the same value
+  driverCache.set(poolUrl, poolDriver);
   return poolDriver;
 }
 
@@ -111,7 +206,7 @@ function getCdpSessionCount(poolUrl) {
   return cdpSessions.get(poolUrl)?.size || 0;
 }
 
-async function getPoolStatusViaCDP(poolUrl, maxSessions) {
+async function getPoolStatusViaCDP(poolUrl, maxSessions, driverName = 'cdp') {
   const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
   try {
     const res = await fetch(`${httpUrl}/json/version`, { signal: AbortSignal.timeout(3000) });
@@ -124,7 +219,7 @@ async function getPoolStatusViaCDP(poolUrl, maxSessions) {
       maxConcurrent: maxSessions,
       queued: 0,
       sessions: [],
-      driver: 'cdp',
+      driver: driverName,
     };
   } catch (error) {
     return {
@@ -134,7 +229,7 @@ async function getPoolStatusViaCDP(poolUrl, maxSessions) {
       maxConcurrent: maxSessions,
       queued: 0,
       sessions: [],
-      driver: 'cdp',
+      driver: driverName,
     };
   }
 }
@@ -143,9 +238,13 @@ async function getPoolStatusViaCDP(poolUrl, maxSessions) {
 
 async function getPoolStatusViaBrowserless(poolUrl) {
   const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+  // FIX: add timeout. Without it, a hung browserless HTTP response (TCP
+  // open but no body) makes `fetch` wait indefinitely, which freezes
+  // `selectPool()` and looks downstream like a 0ms test timeout. Other
+  // drivers (CDP, Steel) already use AbortSignal.timeout(3000); match it.
   const [pressureRes, sessionsRes] = await Promise.all([
-    fetch(`${httpUrl}/pressure`),
-    fetch(`${httpUrl}/sessions`),
+    fetch(`${httpUrl}/pressure`, { signal: AbortSignal.timeout(3000) }),
+    fetch(`${httpUrl}/sessions`, { signal: AbortSignal.timeout(3000) }),
   ]);
 
   const pressure = pressureRes.ok ? await pressureRes.json() : null;
@@ -299,10 +398,19 @@ export async function connectToPool(poolUrl, retries = 3, delay = 2000) {
     return connectToSteelPool(poolUrl, retries, delay);
   }
 
+  // For CDP-family drivers, resolve the canonical webSocketDebuggerUrl from
+  // /json/version so users can configure either http://host:port or
+  // ws://host:port without knowing the driver-specific path
+  // (Obscura requires /devtools/browser; browserless does not).
+  let wsEndpoint = poolUrl;
+  if (driver === 'obscura' || driver === 'lightpanda' || driver === 'cdp') {
+    wsEndpoint = await resolveCdpWsEndpoint(poolUrl);
+  }
+
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
       return await puppeteer.connect({
-        browserWSEndpoint: poolUrl,
+        browserWSEndpoint: wsEndpoint,
         timeout: 30000,
       });
     } catch (error) {
@@ -331,14 +439,40 @@ export async function disconnectFromPool(browser, poolUrl) {
 /** Generates docker-compose.yml and starts the pool */
 export function startPool(config, cwd = null) {
   cwd = cwd || process.cwd();
+  const driver = config.poolDriver || 'auto';
+
+  // Obscura is a single Rust binary — no official image, no compose. Print install/run guidance.
+  if (driver === 'obscura') {
+    const port = config.poolPort || 9222;
+    log('ℹ️', 'Obscura is a local binary, not a Docker pool. Install it once:');
+    log('  ', '  # Linux x86_64');
+    log('  ', '  curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz');
+    log('  ', '  tar xzf obscura-x86_64-linux.tar.gz');
+    log('  ', '  # macOS Apple Silicon');
+    log('  ', '  curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-macos.tar.gz');
+    log('  ', '  # macOS Intel');
+    log('  ', '  curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-macos.tar.gz');
+    log('  ', '  # Arch Linux (AUR)');
+    log('  ', '  yay -S obscura-browser');
+    log('ℹ️', `Then run it (in another shell): obscura serve --port ${port} --stealth`);
+    log('ℹ️', `Set poolUrls in e2e.config.js (any of these works):`);
+    log('  ', `  ['http://127.0.0.1:${port}']                     # auto-discovers ws endpoint`);
+    log('  ', `  ['ws://127.0.0.1:${port}/devtools/browser']       # explicit ws endpoint`);
+    log('  ', `Or export CHROME_POOL_URL=http://127.0.0.1:${port}`);
+    return;
+  }
+
   const poolDir = path.join(cwd, '.e2e-pool');
 
   if (!fs.existsSync(poolDir)) {
     fs.mkdirSync(poolDir, { recursive: true });
   }
 
-  // Read template and interpolate variables
-  const templatePath = path.join(__dirname, '..', 'templates', 'docker-compose.yml');
+  // Select template based on poolDriver
+  const templateFile = driver === 'lightpanda'
+    ? 'docker-compose-lightpanda.yml'
+    : 'docker-compose.yml';
+  const templatePath = path.join(__dirname, '..', 'templates', templateFile);
   let template = fs.readFileSync(templatePath, 'utf-8');
   template = template.replace(/\$\{PORT\}/g, String(config.poolPort || 3333));
   template = template.replace(/\$\{MAX_SESSIONS\}/g, String(config.maxSessions || 5));
@@ -355,14 +489,37 @@ export function startPool(config, cwd = null) {
     }
   }
 
-  log('🐳', 'Starting Chrome Pool...');
-  execFileSync('docker', ['compose', '-f', composePath, 'up', '-d'], { stdio: 'inherit' });
-  log('✅', `Chrome Pool started on port ${config.poolPort || 3333}`);
+  const label = driver === 'lightpanda' ? 'Lightpanda Pool' : 'Chrome Pool';
+  log('🐳', `Starting ${label}...`);
+  const containerMatch = template.match(/container_name:\s*(\S+)/);
+  const containerName = containerMatch ? containerMatch[1].trim() : null;
+  try {
+    execFileSync('docker', ['compose', '-f', composePath, 'up', '-d'], { stdio: 'inherit' });
+  } catch (err) {
+    // Most common failure: a stopped container with the same name lingers from a
+    // previous run, so `up -d` errors with "container name is already in use".
+    // Recover by removing the stale container and recreating cleanly.
+    if (containerName) {
+      log('🔁', `Recovering: removing stale container ${containerName} and retrying...`);
+      try { execFileSync('docker', ['rm', '-f', containerName], { stdio: 'ignore' }); } catch { /* may not exist */ }
+      execFileSync('docker', ['compose', '-f', composePath, 'up', '-d'], { stdio: 'inherit' });
+    } else {
+      throw err;
+    }
+  }
+  log('✅', `${label} started on port ${config.poolPort || 3333}`);
 }
 
 /** Stops the pool */
 export function stopPool(config, cwd = null) {
   cwd = cwd || process.cwd();
+  const driver = config.poolDriver || 'auto';
+
+  if (driver === 'obscura') {
+    log('ℹ️', 'Obscura runs as a local process — stop it with Ctrl-C in its own shell.');
+    return;
+  }
+
   const composePath = path.join(cwd, '.e2e-pool', 'docker-compose.yml');
   if (!fs.existsSync(composePath)) {
     log('⚠️', '.e2e-pool/docker-compose.yml not found');
@@ -383,7 +540,7 @@ export function restartPool(config, cwd = null) {
 /**
  * Gets pool status using the appropriate driver.
  * @param {string} poolUrl - WebSocket URL of the pool
- * @param {object} [options] - { poolDriver: 'auto'|'browserless'|'lightpanda'|'cdp'|'steel', maxSessions: number }
+ * @param {object} [options] - { poolDriver: 'auto'|'browserless'|'cdp'|'lightpanda'|'obscura'|'steel', maxSessions: number }
  */
 export async function getPoolStatus(poolUrl, options = {}) {
   const { poolDriver = 'auto', maxSessions = 10 } = options;
@@ -394,8 +551,8 @@ export async function getPoolStatus(poolUrl, options = {}) {
     return getPoolStatusViaSteel(poolUrl, maxSessions);
   }
 
-  if (driver === 'cdp') {
-    return getPoolStatusViaCDP(poolUrl, maxSessions);
+  if (driver === 'lightpanda' || driver === 'obscura' || driver === 'cdp') {
+    return getPoolStatusViaCDP(poolUrl, maxSessions, driver);
   }
 
   // Browserless driver

package/src/runner.js

@@ -10,9 +10,9 @@ import path from 'path';
 import http from 'http';
 import https from 'https';
 import { connectToPool, getCachedDriver, disconnectFromPool } from './pool.js';
-import { getPoolUrls, selectPool, releasePending } from './pool-manager.js';
+import { getPoolUrls, selectPool, releasePending, resolvePoolsForTest } from './pool-manager.js';
 import { forkAppInstance, destroyFork, isAppPoolEnabled } from './app-pool.js';
-import { executeAction } from './actions.js';
+import { executeAction, pageHasRenderableContent, looksLikeBlankCapture } from './actions.js';
 import { narrateAction } from './narrate.js';
 import { log, colors as C } from './logger.js';
 import { resolveTestData, validateActionTypes } from './module-resolver.js';
@@ -23,6 +23,39 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Best-effort step thumbnail for the storyline view.
+ * Captures once in memory, writes to disk AND returns base64 so callers
+ * can stream the same frame through the live preview WebSocket.
+ * Skips silently on any error so it never breaks a test run.
+ */
+const NO_AUTO_CAPTURE_TYPES = new Set(['screenshot', 'close_tab']);
+async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig, alreadyCaptured) {
+  if (!effectiveConfig.autoCaptureSteps) return null;
+  if (NO_AUTO_CAPTURE_TYPES.has(action?.type)) return null;
+  if (alreadyCaptured) return null;
+  if (!page || (typeof page.isClosed === 'function' && page.isClosed())) return null;
+  // Skip auto-capture when the page can't produce a meaningful image —
+  // about:blank or fully empty DOM — to stop blank step-*.jpg flooding.
+  if (!(await pageHasRenderableContent(page))) return null;
+  try {
+    const safeName = String(testName).replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+    const filename = `step-${safeName}-${String(idx).padStart(3, '0')}-${Date.now()}.jpg`;
+    const filepath = path.join(effectiveConfig.screenshotsDir, filename);
+    const buf = await page.screenshot({
+      type: 'jpeg',
+      quality: effectiveConfig.autoCaptureQuality ?? 60,
+      fullPage: false,
+      encoding: 'binary',
+    });
+    if (looksLikeBlankCapture(buf, 'jpeg')) return null;
+    fs.writeFileSync(filepath, buf);
+    return { path: filepath, base64: buf.toString('base64') };
+  } catch {
+    return null;
+  }
+}
+
 /** Simple glob matching with * wildcards for exclude patterns. */
 function matchesExclude(filename, excludePatterns) {
   if (!excludePatterns?.length) return false;
@@ -190,9 +223,24 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
     }
 
     const driverOpts = { poolDriver: config.poolDriver || 'auto', maxSessions: config.maxSessions || 10 };
-    const chosenPool = await selectPool(getPoolUrls(config), 2000, 60000, driverOpts);
+
+    // CLI override (--driver / --fallback-driver) wins over per-test fields.
+    const requestedDriver = config.cliDriverOverride || test.driver || null;
+    const requestedFallback = config.cliFallbackDriverOverride || test.fallbackDriver || null;
+
+    let candidatePoolUrls = getPoolUrls(config);
+    let driverChoice = null;
+    if (requestedDriver) {
+      const resolved = await resolvePoolsForTest(candidatePoolUrls, requestedDriver, requestedFallback, driverOpts);
+      candidatePoolUrls = resolved.urls;
+      driverChoice = { requested: requestedDriver, used: resolved.driver, usedFallback: resolved.usedFallback };
+      log('🎯', `${C.dim}${test.name}: driver=${resolved.driver}${resolved.usedFallback ? ' (fallback)' : ''}${C.reset}`);
+    }
+
+    const chosenPool = await selectPool(candidatePoolUrls, 2000, 60000, driverOpts);
     result.poolUrl = chosenPool;
     result.poolDriver = getCachedDriver(chosenPool);
+    if (driverChoice) result.driverChoice = driverChoice;
     const poolLabel = chosenPool.replace('ws://', '').replace('wss://', '');
     const isMultiPool = getPoolUrls(config).length > 1;
     if (isMultiPool) {
@@ -236,9 +284,13 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
           maxHeight: config.screencastMaxHeight || 600,
           everyNthFrame: 1,
         }), 5000);
-      } catch {
+        log('📹', `${C.dim}screencast started for ${test.name} (driver=${poolDriver})${C.reset}`);
+      } catch (err) {
+        log('⚠️', `${C.amber}screencast failed for ${test.name}: ${err.message} (driver=${poolDriver})${C.reset}`);
         cdpSession = null;
       }
+    } else if (config.screencast && poolDriver === 'cdp') {
+      log('⚠️', `${C.amber}screencast disabled: pool driver is generic CDP (Lightpanda?), not supported${C.reset}`);
     }
 
     page.on('console', (msg) => {
@@ -440,16 +492,20 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             actionResult = await executeAction(page, action, effectiveConfig);
           }
           const actionDuration = Date.now() - actionStart;
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, !!actionResult?.screenshot);
           const actionEntry = {
             ...action,
             success: true,
             duration: actionDuration,
             result: actionResult,
           };
+          if (autoShot) actionEntry.autoScreenshot = autoShot.path;
           if (attempt > 0) actionEntry.actionRetries = attempt;
           actionEntry.narrative = narrateAction(action, actionEntry);
           result.actions.push(actionEntry);
-          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: true, duration: actionDuration, narrative: actionEntry.narrative, screenshotPath: actionResult?.screenshot || null });
+          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: true, duration: actionDuration, narrative: actionEntry.narrative, screenshotPath: actionResult?.screenshot || null, autoScreenshot: autoShot?.path || null });
+          // Stream the auto-capture as a live frame so the storyline player has something to show even when CDP screencast is silent
+          if (autoShot?.base64) progressFn({ event: 'test:frame', name: test.name, data: autoShot.base64, source: 'step' });
           lastError = null;
           break;
         } catch (error) {
@@ -460,16 +516,19 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             continue;
           }
           const actionDuration = Date.now() - actionStart;
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, false);
           const failedEntry = {
             ...action,
             success: false,
             duration: actionDuration,
             error: error.message,
           };
+          if (autoShot) failedEntry.autoScreenshot = autoShot.path;
           if (maxActionRetries > 0) failedEntry.actionRetries = attempt;
           failedEntry.narrative = narrateAction(action, failedEntry);
           result.actions.push(failedEntry);
-          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: false, duration: actionDuration, narrative: failedEntry.narrative, error: error.message });
+          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: false, duration: actionDuration, narrative: failedEntry.narrative, error: error.message, autoScreenshot: autoShot?.path || null });
+          if (autoShot?.base64) progressFn({ event: 'test:frame', name: test.name, data: autoShot.base64, source: 'step' });
           throw error;
         }
       }
@@ -532,10 +591,18 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
 
     if (page) {
       try {
-        const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const errorScreenshot = path.join(config.screenshotsDir, `error-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: errorScreenshot, fullPage: true });
-        result.errorScreenshot = errorScreenshot;
+        // Only capture when the page actually has something to show.
+        // about:blank / empty-DOM failures produced 5KB blank PNGs that
+        // accumulated in screenshotsDir with no debug value.
+        if (await pageHasRenderableContent(page)) {
+          const errBuf = await page.screenshot({ fullPage: true });
+          if (!looksLikeBlankCapture(errBuf, 'png')) {
+            const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+            const errorScreenshot = path.join(config.screenshotsDir, `error-${safeName}-${Date.now()}.png`);
+            fs.writeFileSync(errorScreenshot, errBuf);
+            result.errorScreenshot = errorScreenshot;
+          }
+        }
       } catch { /* page may be dead */ }
     }
   } finally {

package/src/visual-diff.js

@@ -444,3 +444,72 @@ function buildMaskLookup(regions, imgWidth, imgHeight) {
     return (mask[bit >> 3] & (1 << (bit & 7))) !== 0;
   };
 }
+
+// ── Blank screenshot detection ─────────────────────────────────────────────
+/**
+ * Detects whether a PNG screenshot is "completely blank" — i.e. a single
+ * uniform fill color (a white/empty page, a solid error frame, etc.).
+ *
+ * Strategy: decode to RGBA, sample pixels evenly (capped for speed), compute
+ * the mean color, then count how many sampled pixels deviate from that mean by
+ * more than `tolerance` on any channel. An image is blank when the fraction of
+ * deviating pixels stays at/under `maxOutlierFraction` — this tolerates a few
+ * stray pixels (a cursor, a 1px border) while still requiring a near-uniform
+ * frame. Non-PNG or undecodable files are reported as not-blank so they are
+ * never deleted by mistake.
+ *
+ * @param {string} filePath
+ * @param {{tolerance?:number, maxOutlierFraction?:number, maxSamples?:number}} [opts]
+ * @returns {{blank:boolean, color?:{r:number,g:number,b:number}, brightness?:number,
+ *            width?:number, height?:number, outlierFraction?:number, error?:string}}
+ */
+export function isBlankImage(filePath, opts = {}) {
+  const tolerance = opts.tolerance ?? 10;
+  const maxOutlierFraction = opts.maxOutlierFraction ?? 0.005; // ≤0.5% off-color pixels
+  const maxSamples = opts.maxSamples ?? 120000;
+
+  let img;
+  try {
+    img = decodePNG(filePath);
+  } catch (error) {
+    return { blank: false, error: error.message };
+  }
+
+  const { width, height, data } = img;
+  const totalPixels = width * height;
+  if (totalPixels === 0) return { blank: false, width, height };
+
+  // Even sampling stride so huge captures stay fast without missing regions.
+  const step = Math.max(1, Math.floor(totalPixels / maxSamples));
+
+  let sumR = 0, sumG = 0, sumB = 0, n = 0;
+  for (let p = 0; p < totalPixels; p += step) {
+    const i = p * 4;
+    sumR += data[i]; sumG += data[i + 1]; sumB += data[i + 2];
+    n++;
+  }
+  const meanR = sumR / n, meanG = sumG / n, meanB = sumB / n;
+
+  let outliers = 0;
+  for (let p = 0; p < totalPixels; p += step) {
+    const i = p * 4;
+    if (Math.abs(data[i] - meanR) > tolerance ||
+        Math.abs(data[i + 1] - meanG) > tolerance ||
+        Math.abs(data[i + 2] - meanB) > tolerance) {
+      outliers++;
+    }
+  }
+
+  const outlierFraction = outliers / n;
+  const color = { r: Math.round(meanR), g: Math.round(meanG), b: Math.round(meanB) };
+  const brightness = Math.round((meanR + meanG + meanB) / 3);
+
+  return {
+    blank: outlierFraction <= maxOutlierFraction,
+    color,
+    brightness,
+    width,
+    height,
+    outlierFraction: Math.round(outlierFraction * 1e4) / 1e4,
+  };
+}

package/src/websocket.js

@@ -81,10 +81,21 @@ export function createWebSocketServer(httpServer, options = {}) {
   const clients = new Set();
 
   httpServer.on('upgrade', (req, socket, head) => {
-    // Validate Origin to prevent cross-site WebSocket hijacking
+    // Validate Origin to prevent cross-site WebSocket hijacking.
+    // Allow if: no Origin (curl/scripts), explicit whitelist match, or same-origin
+    // (Origin's host == the Host header the client connected to).
     const origin = req.headers.origin;
-    if (origin && options.allowedOrigins) {
-      if (!options.allowedOrigins.includes(origin)) {
+    const host = req.headers.host;
+    if (origin) {
+      let allowed = false;
+      if (options.allowedOrigins && options.allowedOrigins.includes(origin)) allowed = true;
+      if (!allowed && host) {
+        try {
+          const u = new URL(origin);
+          if (u.host === host) allowed = true;
+        } catch { /* malformed origin */ }
+      }
+      if (!allowed) {
         socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
         socket.destroy();
         return;