human-browser 3.9.2 → 4.0.0

package/scripts/browser-human.js

@@ -1,44 +1,30 @@
 /**
- * browser-human.js
+ * browser-human.js — Human Browser for AI Agents v4.0.0
  *
- * Stealth browser — iPhone 15 Pro, Romania residential proxy, human-like behavior.
- * Bypasses Cloudflare, DataDome, PerimeterX, bot detection.
+ * Stealth browser with residential proxies from 10+ countries.
+ * Appears as iPhone 15 Pro or Desktop Chrome to every website.
+ * Bypasses Cloudflare, DataDome, PerimeterX out of the box.
  *
- * Usage:
- *   const { launchHuman } = require('./browser-human');
- *   const { browser, page } = await launchHuman();         // mobile (iPhone)
- *   const { browser, page } = await launchHuman({ mobile: false }); // desktop
- *
- * Proxy config via env vars (override defaults):
- *   HB_PROXY_SERVER   — e.g. http://ro.decodo.com:13001 (full override)
- *   HB_PROXY_USER     — your proxy username (or call getTrial() for free trial)
- *   HB_PROXY_PASS     — password
- *   HB_PROXY_COUNTRY  — country code: ro, us, de, gb, fr, nl, sg... (default: ro)
- *   HB_PROXY_SESSION  — Decodo: sticky port 10001-49999 (unique IP per user)
- *   HB_NO_PROXY       — set to "1" to disable proxy entirely
+ * Get credentials: https://humanbrowser.dev
+ * Support: https://t.me/virixlabs
  *
- * Unique IP per user (Decodo sticky sessions):
- *   Each port in 10001-49999 = different sticky IP.
- *   Set HB_PROXY_SESSION=<random_port> at deploy time for per-user unique IP.
- *   Country via HB_PROXY_COUNTRY or launchHuman({ country: 'us' }).
- *
- * Supported providers (built-in presets):
- *   brightdata  — brd.superproxy.io:33335 (residential_proxy1_roma)
- *   decodo      — gate.decodo.com:10001  (Decodo/Smartproxy)
- *   iproyal     — geo.iproyal.com:12321  (IPRoyal)
- *   nodemaven   — rp.nodemavenio.com:10001 (NodeMaven)
+ * Usage:
+ *   const { launchHuman, getTrial } = require('./browser-human');
+ *   const { browser, page } = await launchHuman({ country: 'us' });
  *
- * ⚠️  Bright Data KYC note:
- *   GET requests work without KYC. POST requests require KYC verification
- *   at https://brightdata.com/cp/kyc — takes ~5 min.
- *   For full functionality (form submissions, APIs), complete KYC or use
- *   Decodo/IPRoyal which allow POST without extra verification.
+ * Proxy config via env vars:
+ *   HB_PROXY_PROVIDER  — decodo | brightdata | iproyal | nodemaven (default: decodo)
+ *   HB_PROXY_USER      — proxy username
+ *   HB_PROXY_PASS      — proxy password
+ *   HB_PROXY_SERVER    — full override: http://host:port
+ *   HB_PROXY_COUNTRY   — country code: ro, us, de, gb, fr, nl, sg... (default: ro)
+ *   HB_PROXY_SESSION   — Decodo sticky port 10001-49999 (unique IP per user)
+ *   HB_NO_PROXY        — set to "1" to disable proxy entirely
  */
 
-// Playwright path resolution — works in multiple contexts:
-// 1. clawhub install → ~/.agents/skills/human-browser/
-// 2. workspace usage → /root/.openclaw/workspace/
-// 3. Clawster containers → /root/.openclaw/workspace/
+// ─── PLAYWRIGHT RESOLVER ──────────────────────────────────────────────────────
+// Works in any context: clawhub install, workspace, Clawster containers
+
 function _requirePlaywright() {
   const tries = [
     () => require('playwright'),
@@ -50,36 +36,100 @@ function _requirePlaywright() {
   for (const fn of tries) {
     try { return fn(); } catch (_) {}
   }
-  throw new Error('[human-browser] playwright not found.\nRun: npm install playwright && npx playwright install chromium');
+  throw new Error(
+    '[human-browser] playwright not found.\n' +
+    'Run: npm install playwright && npx playwright install chromium'
+  );
 }
+
 const { chromium } = _requirePlaywright();
 
-// ─── PROXY CONFIG ─────────────────────────────────────────────────────────────
-// Built-in provider presets
+// ─── COUNTRY CONFIGS ──────────────────────────────────────────────────────────
+
+const COUNTRY_META = {
+  ro: { locale: 'ro-RO', tz: 'Europe/Bucharest',  lat: 44.4268,  lon: 26.1025,   lang: 'ro-RO,ro;q=0.9,en-US;q=0.8,en;q=0.7' },
+  us: { locale: 'en-US', tz: 'America/New_York',  lat: 40.7128,  lon: -74.006,   lang: 'en-US,en;q=0.9' },
+  uk: { locale: 'en-GB', tz: 'Europe/London',     lat: 51.5074,  lon: -0.1278,   lang: 'en-GB,en;q=0.9' },
+  gb: { locale: 'en-GB', tz: 'Europe/London',     lat: 51.5074,  lon: -0.1278,   lang: 'en-GB,en;q=0.9' },
+  de: { locale: 'de-DE', tz: 'Europe/Berlin',     lat: 52.5200,  lon: 13.4050,   lang: 'de-DE,de;q=0.9,en;q=0.8' },
+  nl: { locale: 'nl-NL', tz: 'Europe/Amsterdam',  lat: 52.3676,  lon: 4.9041,    lang: 'nl-NL,nl;q=0.9,en;q=0.8' },
+  jp: { locale: 'ja-JP', tz: 'Asia/Tokyo',        lat: 35.6762,  lon: 139.6503,  lang: 'ja-JP,ja;q=0.9,en;q=0.8' },
+  fr: { locale: 'fr-FR', tz: 'Europe/Paris',      lat: 48.8566,  lon: 2.3522,    lang: 'fr-FR,fr;q=0.9,en;q=0.8' },
+  ca: { locale: 'en-CA', tz: 'America/Toronto',   lat: 43.6532,  lon: -79.3832,  lang: 'en-CA,en;q=0.9' },
+  au: { locale: 'en-AU', tz: 'Australia/Sydney',  lat: -33.8688, lon: 151.2093,  lang: 'en-AU,en;q=0.9' },
+  sg: { locale: 'en-SG', tz: 'Asia/Singapore',    lat: 1.3521,   lon: 103.8198,  lang: 'en-SG,en;q=0.9' },
+  br: { locale: 'pt-BR', tz: 'America/Sao_Paulo', lat: -23.5505, lon: -46.6333,  lang: 'pt-BR,pt;q=0.9,en;q=0.8' },
+  in: { locale: 'en-IN', tz: 'Asia/Kolkata',      lat: 28.6139,  lon: 77.2090,   lang: 'en-IN,en;q=0.9,hi;q=0.8' },
+};
+
+// ─── DEVICE PROFILES ─────────────────────────────────────────────────────────
+
+function buildDevice(mobile, country = 'ro') {
+  const meta = COUNTRY_META[country.toLowerCase()] || COUNTRY_META.ro;
+
+  if (mobile) {
+    return {
+      userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1',
+      viewport: { width: 393, height: 852 },
+      deviceScaleFactor: 3,
+      isMobile: true,
+      hasTouch: true,
+      locale: meta.locale,
+      timezoneId: meta.tz,
+      geolocation: { latitude: meta.lat, longitude: meta.lon, accuracy: 50 },
+      colorScheme: 'light',
+      extraHTTPHeaders: {
+        'Accept-Language': meta.lang,
+        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        'Accept-Encoding': 'gzip, deflate, br',
+        'sec-fetch-dest': 'document',
+        'sec-fetch-mode': 'navigate',
+        'sec-fetch-site': 'none',
+      },
+    };
+  }
+
+  return {
+    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+    viewport: { width: 1440, height: 900 },
+    locale: meta.locale,
+    timezoneId: meta.tz,
+    geolocation: { latitude: meta.lat, longitude: meta.lon, accuracy: 50 },
+    colorScheme: 'light',
+    extraHTTPHeaders: {
+      'Accept-Language': meta.lang,
+      'sec-ch-ua': '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+      'sec-ch-ua-mobile': '?0',
+      'sec-ch-ua-platform': '"Windows"',
+    },
+  };
+}
+
+// ─── PROXY PRESETS ────────────────────────────────────────────────────────────
+// ⚠️  defaultUser/defaultPass are ALWAYS null — credentials come from env vars
+//     or getTrial(). NEVER hardcode credentials here.
+
 const PROXY_PRESETS = {
-  brightdata: {
-    server: 'http://brd.superproxy.io:33335',
-    usernameTemplate: (user, country, session) =>
-      `${user}-country-${country}-session-${session}`,
-    defaultUser: null, // set via HB_PROXY_USER or call getTrial()
-    defaultPass: null, // set via HB_PROXY_PASS or call getTrial()
-    defaultCountry: 'ro',
-  },
   decodo: {
-    // Country-specific hostname: {country}.decodo.com
-    // Sticky session = port number (10001-49999), each port = unique IP
+    // Sticky session via port number: each unique port = unique sticky IP
     serverTemplate: (country, port) => `http://${country}.decodo.com:${port}`,
     usernameTemplate: (user) => user,
-    defaultUser: null, // set via HB_PROXY_USER or call getTrial()
-    defaultPass: null, // set via HB_PROXY_PASS or call getTrial()
+    defaultUser: null,
+    defaultPass: null,
     defaultCountry: 'ro',
-    // Port range for sticky sessions
     stickyPortMin: 10001,
     stickyPortMax: 49999,
   },
+  brightdata: {
+    server: 'http://brd.superproxy.io:33335',
+    usernameTemplate: (user, country, session) =>
+      `${user}-country-${country}-session-${session}`,
+    defaultUser: null,
+    defaultPass: null,
+    defaultCountry: 'ro',
+  },
   iproyal: {
     server: 'http://geo.iproyal.com:12321',
-    // IPRoyal uses password suffix for options
     usernameTemplate: (user) => user,
     passwordTemplate: (pass, country, session) =>
       `${pass}_country-${country}_session-${session}_lifetime-30m`,
@@ -97,16 +147,14 @@ const PROXY_PRESETS = {
   },
 };
 
-// Active provider: env var HB_PROXY_PROVIDER or 'decodo'
-const ACTIVE_PROVIDER = process.env.HB_PROXY_PROVIDER || 'decodo';
-const preset = PROXY_PRESETS[ACTIVE_PROVIDER] || PROXY_PRESETS.brightdata;
-
 function makeProxy(sessionId = null, country = null) {
   if (process.env.HB_NO_PROXY === '1') return null;
 
-  const cty = (country || process.env.HB_PROXY_COUNTRY || preset.defaultCountry).toLowerCase();
+  const providerName = process.env.HB_PROXY_PROVIDER || 'decodo';
+  const preset = PROXY_PRESETS[providerName] || PROXY_PRESETS.decodo;
+  const cty = (country || process.env.HB_PROXY_COUNTRY || preset.defaultCountry || 'ro').toLowerCase();
 
-  // Allow full override via env vars
+  // Full manual override
   if (process.env.HB_PROXY_SERVER && process.env.HB_PROXY_USER) {
     return {
       server: process.env.HB_PROXY_SERVER,
@@ -115,227 +163,157 @@ function makeProxy(sessionId = null, country = null) {
     };
   }
 
-  const user = process.env.HB_PROXY_USER || preset.defaultUser;
-  const pass = process.env.HB_PROXY_PASS || preset.defaultPass;
+  // Legacy env var support
+  const user = process.env.HB_PROXY_USER || process.env.PROXY_USER || process.env.PROXY_USERNAME || preset.defaultUser;
+  const pass = process.env.HB_PROXY_PASS || process.env.PROXY_PASS || process.env.PROXY_PASSWORD || preset.defaultPass;
+
   if (!user || !pass) {
-    console.warn(`[browser-human] No proxy credentials for provider "${ACTIVE_PROVIDER}". Set HB_PROXY_USER/HB_PROXY_PASS.`);
+    console.warn(`[browser-human] No proxy credentials for "${providerName}". Call getTrial() or set HB_PROXY_USER/HB_PROXY_PASS.`);
     return null;
   }
 
-  // Decodo: sticky session via port number (10001-49999 range)
-  // Each unique port = unique sticky IP. HB_PROXY_SESSION stores the port.
-  let server;
+  // Decodo: port-based sticky sessions
   if (preset.serverTemplate) {
     const portMin = preset.stickyPortMin || 10001;
     const portMax = preset.stickyPortMax || 49999;
-    const sessionPort = sessionId
+    const port = sessionId
       ? parseInt(sessionId)
       : (process.env.HB_PROXY_SESSION
           ? parseInt(process.env.HB_PROXY_SESSION)
           : Math.floor(Math.random() * (portMax - portMin + 1)) + portMin);
-    server = preset.serverTemplate(cty, sessionPort);
-  } else {
-    const sid = sessionId || process.env.HB_PROXY_SESSION || Math.random().toString(36).slice(2, 10);
-    server = preset.server;
-    const username = preset.usernameTemplate(user, cty, sid);
-    const password = preset.passwordTemplate ? preset.passwordTemplate(pass, cty, sid) : pass;
+    const server = preset.serverTemplate(cty, port);
+    const username = preset.usernameTemplate(user, cty, port);
+    const password = preset.passwordTemplate
+      ? preset.passwordTemplate(pass, cty, port)
+      : pass;
     return { server, username, password };
   }
 
-  const username = preset.usernameTemplate(user, cty);
-  const password = preset.passwordTemplate
-    ? preset.passwordTemplate(pass, cty)
-    : pass;
-
+  // Other providers: session-string based
+  const sid = sessionId || process.env.HB_PROXY_SESSION || Math.random().toString(36).slice(2, 10);
+  const server = preset.server;
+  const username = preset.usernameTemplate(user, cty, sid);
+  const password = preset.passwordTemplate ? preset.passwordTemplate(pass, cty, sid) : pass;
   return { server, username, password };
 }
 
-// Default PROXY (random session per launch)
-const PROXY = makeProxy();
-
 // ─── TRIAL CREDENTIALS ───────────────────────────────────────────────────────
 
 /**
  * Get free trial credentials from humanbrowser.dev
  * Sets HB_PROXY_USER, HB_PROXY_PASS, HB_PROXY_SESSION, HB_PROXY_PROVIDER
- * No signup needed — ~1GB Romania residential + 10 captcha solves
+ * No signup needed — Romania residential proxy
  *
  * @example
- *   const { launchHuman, getTrial } = require('./browser-human');
  *   await getTrial();
  *   const { page } = await launchHuman(); // now uses trial proxy
  */
 async function getTrial() {
-  if (process.env.HB_PROXY_USER) {
+  if (process.env.HB_PROXY_USER || process.env.PROXY_USER) {
     console.log('[human-browser] Credentials already set, skipping trial fetch.');
     return { ok: true, cached: true };
   }
   try {
     const https = require('https');
     const data = await new Promise((resolve, reject) => {
-      https.get('https://humanbrowser.dev/api/trial', res => {
+      const req = https.get('https://humanbrowser.dev/api/trial', res => {
         let body = '';
         res.on('data', d => body += d);
-        res.on('end', () => {
-          try { resolve(JSON.parse(body)); } catch (e) { reject(e); }
-        });
-      }).on('error', reject);
+        res.on('end', () => { try { resolve(JSON.parse(body)); } catch (e) { reject(e); } });
+      });
+      req.on('error', reject);
+      req.setTimeout(10000, () => { req.destroy(); reject(new Error('Trial request timed out')); });
     });
+
     if (data.proxy_user || data.PROXY_USER) {
-      const user = data.proxy_user || data.PROXY_USER;
-      const pass = data.proxy_pass || data.PROXY_PASS;
-      const session = data.session || data.PROXY_SESSION || String(Math.floor(Math.random() * 39999) + 10001);
+      const user     = data.proxy_user || data.PROXY_USER;
+      const pass     = data.proxy_pass || data.PROXY_PASS;
+      const session  = data.session || data.PROXY_SESSION || String(Math.floor(Math.random() * 39999) + 10001);
       const provider = data.provider || 'decodo';
-      const country = data.country || 'ro';
+      const country  = data.country || 'ro';
+
       process.env.HB_PROXY_PROVIDER = provider;
-      process.env.HB_PROXY_USER = user;
-      process.env.HB_PROXY_PASS = pass;
-      process.env.HB_PROXY_SESSION = session;
-      process.env.HB_PROXY_COUNTRY = process.env.HB_PROXY_COUNTRY || country;
-      console.log(`[human-browser] Trial ready: ${provider} ${country.toUpperCase()} proxy`);
+      process.env.HB_PROXY_USER     = user;
+      process.env.HB_PROXY_PASS     = pass;
+      process.env.HB_PROXY_SESSION  = session;
+      if (!process.env.HB_PROXY_COUNTRY) process.env.HB_PROXY_COUNTRY = country;
+
+      console.log(`🎉 Human Browser trial activated! (~100MB Romania residential IP)`);
+      console.log(`   Upgrade at: https://humanbrowser.dev\n`);
       return { ok: true, provider, country, session };
     }
+
     throw new Error(data.error || 'No credentials in trial response');
   } catch (err) {
+    const e = new Error(err.message);
+    e.code = 'TRIAL_UNAVAILABLE';
+    e.cta_url = 'https://humanbrowser.dev';
     console.warn('[human-browser] Trial fetch failed:', err.message);
-    console.warn('  → Get credentials at: https://humanbrowser.dev');
-    return { ok: false, error: err.message };
+    console.warn('   → Get credentials at: https://humanbrowser.dev');
+    throw e;
   }
 }
 
-// iPhone 15 Pro — самый популярный iOS девайс 2024
-const IPHONE15 = {
-  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1',
-  viewport: { width: 393, height: 852 },
-  deviceScaleFactor: 3,
-  isMobile: true,
-  hasTouch: true,
-  locale: 'ro-RO',
-  timezoneId: 'Europe/Bucharest',
-  geolocation: { latitude: 44.4268, longitude: 26.1025, accuracy: 50 }, // Bucharest
-  colorScheme: 'light',
-  // HTTP headers that iOS Safari sends
-  extraHTTPHeaders: {
-    'Accept-Language': 'ro-RO,ro;q=0.9,en-US;q=0.8,en;q=0.7',
-    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
-    'Accept-Encoding': 'gzip, deflate, br',
-    'sec-fetch-dest': 'document',
-    'sec-fetch-mode': 'navigate',
-    'sec-fetch-site': 'none',
-  }
-};
-
-// Desktop Chrome (Windows) — для сайтов которые не работают на мобиле
-const DESKTOP_RO = {
-  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
-  viewport: { width: 1440, height: 900 },
-  locale: 'ro-RO',
-  timezoneId: 'Europe/Bucharest',
-  geolocation: { latitude: 44.4268, longitude: 26.1025, accuracy: 50 },
-  colorScheme: 'light',
-  extraHTTPHeaders: {
-    'Accept-Language': 'ro-RO,ro;q=0.9,en-US;q=0.8',
-    'sec-ch-ua': '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
-    'sec-ch-ua-mobile': '?0',
-    'sec-ch-ua-platform': '"Windows"',
-  }
-};
-
 // ─── HUMAN BEHAVIOR ───────────────────────────────────────────────────────────
 
-/** Random delay between min and max ms */
 const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-const rand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+const rand  = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
 
 /**
- * Move mouse along a natural curved path (Bezier-like)
- * Not a straight line — humans never move in straight lines
+ * Move mouse along a natural cubic Bezier curve path
  */
 async function humanMouseMove(page, toX, toY, fromX = null, fromY = null) {
-  const pos = await page.evaluate(() => ({ x: window.mouseX || 400, y: window.mouseY || 400 }));
-  const startX = fromX ?? pos.x;
-  const startY = fromY ?? pos.y;
-  
-  // Generate control points for bezier curve
-  const cp1x = startX + rand(-80, 80);
-  const cp1y = startY + rand(-60, 60);
-  const cp2x = toX + rand(-50, 50);
-  const cp2y = toY + rand(-40, 40);
-  
+  const startX = fromX ?? rand(100, 300);
+  const startY = fromY ?? rand(200, 600);
+  const cp1x = startX + rand(-80, 80), cp1y = startY + rand(-60, 60);
+  const cp2x = toX   + rand(-50, 50), cp2y = toY   + rand(-40, 40);
   const steps = rand(12, 25);
-  
   for (let i = 0; i <= steps; i++) {
     const t = i / steps;
-    // Cubic bezier
-    const x = Math.round(
-      Math.pow(1-t, 3) * startX +
-      3 * Math.pow(1-t, 2) * t * cp1x +
-      3 * (1-t) * Math.pow(t, 2) * cp2x +
-      Math.pow(t, 3) * toX
-    );
-    const y = Math.round(
-      Math.pow(1-t, 3) * startY +
-      3 * Math.pow(1-t, 2) * t * cp1y +
-      3 * (1-t) * Math.pow(t, 2) * cp2y +
-      Math.pow(t, 3) * toY
-    );
+    const x = Math.round(Math.pow(1-t,3)*startX + 3*Math.pow(1-t,2)*t*cp1x + 3*(1-t)*t*t*cp2x + t*t*t*toX);
+    const y = Math.round(Math.pow(1-t,3)*startY + 3*Math.pow(1-t,2)*t*cp1y + 3*(1-t)*t*t*cp2y + t*t*t*toY);
     await page.mouse.move(x, y);
-    // Variable speed — faster in middle, slower at start/end
-    const delay = t < 0.2 || t > 0.8 ? rand(8, 20) : rand(2, 8);
-    await sleep(delay);
+    await sleep(t < 0.2 || t > 0.8 ? rand(8, 20) : rand(2, 8));
   }
 }
 
 /**
- * Human-like click with natural mouse movement
+ * Human-like click with curved mouse path
  */
-async function humanClick(page, x, y, opts = {}) {
+async function humanClick(page, x, y) {
   await humanMouseMove(page, x, y);
-  await sleep(rand(50, 180)); // Brief pause before click
+  await sleep(rand(50, 180));
   await page.mouse.down();
-  await sleep(rand(40, 100)); // Hold duration
+  await sleep(rand(40, 100));
   await page.mouse.up();
-  await sleep(rand(100, 300)); // Post-click pause
+  await sleep(rand(100, 300));
 }
 
 /**
- * Human-like type — variable speed, occasional micro-pause
+ * Human-like typing: variable speed (60–220ms/char), occasional micro-pauses
  */
-async function humanType(page, selector, text, opts = {}) {
+async function humanType(page, selector, text) {
   const el = await page.$(selector);
   if (!el) throw new Error(`Element not found: ${selector}`);
-  
-  // Click to focus
   const box = await el.boundingBox();
-  if (box) await humanClick(page, box.x + box.width/2, box.y + box.height/2);
+  if (box) await humanClick(page, box.x + box.width / 2, box.y + box.height / 2);
   await sleep(rand(200, 500));
-  
-  // Type character by character
   for (const char of text) {
     await page.keyboard.type(char);
-    // Variable typing speed: 80-250ms per char (average human is ~100-150ms)
-    const delay = rand(60, 220);
-    await sleep(delay);
-    
-    // Occasional longer pause (thinking)
+    await sleep(rand(60, 220));
     if (Math.random() < 0.08) await sleep(rand(400, 900));
   }
-  
   await sleep(rand(200, 400));
 }
 
 /**
- * Human-like scroll — smooth, variable speed, realistic
+ * Human-like scroll: smooth, multi-step, with jitter
  */
 async function humanScroll(page, direction = 'down', amount = null) {
   const scrollAmount = amount || rand(200, 600);
   const delta = direction === 'down' ? scrollAmount : -scrollAmount;
-  
-  // Move to random position first
   const vp = page.viewportSize();
   await humanMouseMove(page, rand(100, vp.width - 100), rand(200, vp.height - 200));
-  
-  // Scroll in small increments
   const steps = rand(4, 10);
   for (let i = 0; i < steps; i++) {
     await page.mouse.wheel(0, delta / steps + rand(-5, 5));
@@ -345,41 +323,38 @@ async function humanScroll(page, direction = 'down', amount = null) {
 }
 
 /**
- * Human-like page read pause (look around the page)
+ * Read pause — wait as if reading the page, occasional scroll
  */
 async function humanRead(page, minMs = 1500, maxMs = 4000) {
   await sleep(rand(minMs, maxMs));
-  // Occasional small scroll while reading
-  if (Math.random() < 0.3) {
-    await humanScroll(page, 'down', rand(50, 150));
-  }
+  if (Math.random() < 0.3) await humanScroll(page, 'down', rand(50, 150));
 }
 
 // ─── 2CAPTCHA SOLVER ──────────────────────────────────────────────────────────
 
 /**
- * Auto-detect and solve any captcha on the current page via 2captcha.com
- *
- * Supported: reCAPTCHA v2, reCAPTCHA v3, hCaptcha, Cloudflare Turnstile
+ * Auto-detect and solve reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile via 2captcha.com
+ * Token is auto-injected into the page — just submit the form after calling this.
  *
- * Usage:
- *   const { token, type } = await solveCaptcha(page);
- *   // Token is auto-injected into the page. You just submit the form.
+ * @param {Page}   page
+ * @param {Object} opts
+ * @param {string} opts.apiKey     — 2captcha API key (default: env TWOCAPTCHA_KEY)
+ * @param {string} opts.action     — reCAPTCHA v3 action (default: 'verify')
+ * @param {number} opts.minScore   — reCAPTCHA v3 min score (default: 0.7)
+ * @param {number} opts.timeout    — max wait ms (default: 120000)
+ * @param {boolean} opts.verbose   — log progress (default: false)
  *
- * Options:
- *   apiKey    — 2captcha API key (default: env TWOCAPTCHA_KEY)
- *   action    — reCAPTCHA v3 action (default: 'verify')
- *   minScore  — reCAPTCHA v3 min score (default: 0.7)
- *   timeout   — max wait ms (default: 120000)
- *   verbose   — log progress (default: false)
+ * @example
+ *   const { token, type } = await solveCaptcha(page, { verbose: true });
+ *   await page.click('button[type=submit]');
  */
 async function solveCaptcha(page, opts = {}) {
   const {
-    apiKey = process.env.TWOCAPTCHA_KEY || '14cbfeed64fea439d5c055111d6760e5',
-    action = 'verify',
+    apiKey   = process.env.TWOCAPTCHA_KEY,
+    action   = 'verify',
     minScore = 0.7,
-    timeout = 120000,
-    verbose = false,
+    timeout  = 120000,
+    verbose  = false,
   } = opts;
 
   if (!apiKey) throw new Error('[2captcha] No API key. Set TWOCAPTCHA_KEY env or pass opts.apiKey');
@@ -387,167 +362,118 @@ async function solveCaptcha(page, opts = {}) {
   const log = verbose ? (...a) => console.log('[2captcha]', ...a) : () => {};
   const pageUrl = page.url();
 
-  // ─── Auto-detect captcha type ───────────────────────────────────────────────
+  // Auto-detect captcha type
   const detected = await page.evaluate(() => {
-    // reCAPTCHA v2/v3
     const rc = document.querySelector('.g-recaptcha, [data-sitekey]');
     if (rc) {
       const sitekey = rc.getAttribute('data-sitekey') || rc.getAttribute('data-key');
       const version = rc.getAttribute('data-version') || (typeof window.grecaptcha !== 'undefined' && 'v2');
       return { type: 'recaptcha', sitekey, version: version === 'v3' ? 'v3' : 'v2' };
     }
-    // hCaptcha
     const hc = document.querySelector('.h-captcha, [data-hcaptcha-sitekey]');
-    if (hc) {
-      const sitekey = hc.getAttribute('data-sitekey') || hc.getAttribute('data-hcaptcha-sitekey');
-      return { type: 'hcaptcha', sitekey };
-    }
-    // Cloudflare Turnstile
+    if (hc) return { type: 'hcaptcha', sitekey: hc.getAttribute('data-sitekey') || hc.getAttribute('data-hcaptcha-sitekey') };
     const ts = document.querySelector('.cf-turnstile, [data-cf-turnstile-sitekey]');
-    if (ts) {
-      const sitekey = ts.getAttribute('data-sitekey') || ts.getAttribute('data-cf-turnstile-sitekey');
-      return { type: 'turnstile', sitekey };
-    }
-    // Also check script tags for sitekeys
-    const scripts = [...document.scripts].map(s => s.src + s.textContent);
-    const combined = scripts.join(' ');
-    const rcMatch = combined.match(/(?:sitekey|data-sitekey)['":\s]+([A-Za-z0-9_-]{40,})/);
+    if (ts) return { type: 'turnstile', sitekey: ts.getAttribute('data-sitekey') || ts.getAttribute('data-cf-turnstile-sitekey') };
+    const scripts = [...document.scripts].map(s => s.src + s.textContent).join(' ');
+    const rcMatch = scripts.match(/(?:sitekey|data-sitekey)['":\s]+([A-Za-z0-9_-]{40,})/);
     if (rcMatch) return { type: 'recaptcha', sitekey: rcMatch[1], version: 'v2' };
-
     return null;
   });
 
-  if (!detected || !detected.sitekey) {
-    throw new Error('[2captcha] No captcha detected on page. Check manually.');
+  if (!detected || !detected.sitekey) throw new Error('[2captcha] No captcha detected on page.');
+  log(`Detected ${detected.type} v${detected.version || ''}`, detected.sitekey.slice(0, 20) + '...');
+
+  // Submit to 2captcha
+  let submitUrl = `https://2captcha.com/in.php?key=${apiKey}&json=1&pageurl=${encodeURIComponent(pageUrl)}&googlekey=${encodeURIComponent(detected.sitekey)}`;
+  if (detected.type === 'recaptcha') {
+    submitUrl += `&method=userrecaptcha`;
+    if (detected.version === 'v3') submitUrl += `&version=v3&action=${action}&min_score=${minScore}`;
+  } else if (detected.type === 'hcaptcha') {
+    submitUrl += `&method=hcaptcha&sitekey=${encodeURIComponent(detected.sitekey)}`;
+  } else if (detected.type === 'turnstile') {
+    submitUrl += `&method=turnstile&sitekey=${encodeURIComponent(detected.sitekey)}`;
   }
 
-  log(`Detected ${detected.type} v${detected.version || ''}`, detected.sitekey.slice(0, 20) + '...');
-  log(`Page: ${pageUrl}`);
+  const submitResp = await fetch(submitUrl);
+  const submitData = await submitResp.json();
+  if (!submitData.status || submitData.status !== 1) throw new Error(`[2captcha] Submit failed: ${JSON.stringify(submitData)}`);
+  const taskId = submitData.request;
+  log(`Task submitted: ${taskId} — waiting for workers...`);
 
-  // ─── Route: trial proxy OR direct 2captcha ─────────────────────────────────
-  const captchaProxyUrl = opts.captchaUrl || process.env.CAPTCHA_URL;
-  const captchaToken    = opts.captchaToken || process.env.CAPTCHA_TOKEN;
   let token = null;
-
-  if (captchaProxyUrl && captchaToken) {
-    // Trial mode: VPS proxy handles 2captcha + tracks usage
-    log(`Using trial captcha proxy: ${captchaProxyUrl}`);
-    const methodMap = { recaptcha: detected.version === 'v3' ? 'recaptcha_v3' : 'recaptcha_v2', hcaptcha: 'hcaptcha', turnstile: 'turnstile' };
-    const resp = await fetch(captchaProxyUrl, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ trial_token: captchaToken, sitekey: detected.sitekey, method: methodMap[detected.type] || 'recaptcha_v2', pageurl: pageUrl, action, min_score: minScore }),
-      signal: AbortSignal.timeout(timeout),
-    });
-    const data = await resp.json();
-    if (!data.ok) {
-      const err = new Error(data.error || 'Captcha proxy failed');
-      err.upgrade_url = data.upgrade_url || 'https://humanbrowser.dev';
-      err.solves_remaining = data.solves_remaining ?? 0;
-      throw err;
-    }
-    token = data.token;
-    log(`✅ Solved via proxy! Solves remaining: ${data.solves_remaining}`);
-  } else {
-    // Direct 2captcha mode
-    if (!apiKey) throw new Error('[2captcha] No API key. Get a trial at humanbrowser.dev');
-    let submitUrl = `https://2captcha.com/in.php?key=${apiKey}&json=1&pageurl=${encodeURIComponent(pageUrl)}&googlekey=${encodeURIComponent(detected.sitekey)}`;
-    if (detected.type === 'recaptcha') {
-      submitUrl += `&method=userrecaptcha`;
-      if (detected.version === 'v3') submitUrl += `&version=v3&action=${action}&min_score=${minScore}`;
-    } else if (detected.type === 'hcaptcha') {
-      submitUrl += `&method=hcaptcha&sitekey=${encodeURIComponent(detected.sitekey)}`;
-    } else if (detected.type === 'turnstile') {
-      submitUrl += `&method=turnstile&sitekey=${encodeURIComponent(detected.sitekey)}`;
-    }
-    const submitResp = await fetch(submitUrl);
-    const submitData = await submitResp.json();
-    if (!submitData.status || submitData.status !== 1) throw new Error(`[2captcha] Submit failed: ${JSON.stringify(submitData)}`);
-    const taskId = submitData.request;
-    log(`Task submitted: ${taskId} — waiting for workers...`);
-
-    const maxAttempts = Math.floor(timeout / 5000);
-    for (let i = 0; i < maxAttempts; i++) {
-      await sleep(i === 0 ? 15000 : 5000);
-      const pollResp = await fetch(`https://2captcha.com/res.php?key=${apiKey}&action=get&id=${taskId}&json=1`);
-      const pollData = await pollResp.json();
-      if (pollData.status === 1) { token = pollData.request; log(`✅ Solved!`); break; }
-      if (pollData.request !== 'CAPCHA_NOT_READY') throw new Error(`[2captcha] Poll error: ${JSON.stringify(pollData)}`);
-      log(`⏳ Attempt ${i + 1}/${maxAttempts} — not ready yet...`);
-    }
-    if (!token) throw new Error('[2captcha] Timeout waiting for captcha solution');
+  const maxAttempts = Math.floor(timeout / 5000);
+  for (let i = 0; i < maxAttempts; i++) {
+    await sleep(i === 0 ? 15000 : 5000);
+    const pollResp = await fetch(`https://2captcha.com/res.php?key=${apiKey}&action=get&id=${taskId}&json=1`);
+    const pollData = await pollResp.json();
+    if (pollData.status === 1) { token = pollData.request; log('✅ Solved!'); break; }
+    if (pollData.request !== 'CAPCHA_NOT_READY') throw new Error(`[2captcha] Poll error: ${JSON.stringify(pollData)}`);
+    log(`⏳ Attempt ${i + 1}/${maxAttempts}...`);
   }
+  if (!token) throw new Error('[2captcha] Timeout waiting for captcha solution');
 
-  // ─── Inject token into page ─────────────────────────────────────────────────
+  // Inject token into page
   await page.evaluate(({ type, token }) => {
-    // reCAPTCHA
     if (type === 'recaptcha' || type === 'turnstile') {
-      const textarea = document.querySelector('#g-recaptcha-response, [name="g-recaptcha-response"]');
-      if (textarea) {
-        textarea.style.display = 'block';
-        textarea.value = token;
-        textarea.dispatchEvent(new Event('change', { bubbles: true }));
-      }
-      // Also try callback
-      if (typeof window.___grecaptcha_cfg !== 'undefined') {
-        try {
-          const clients = window.___grecaptcha_cfg.clients;
-          if (clients) {
-            Object.values(clients).forEach(client => {
-              Object.values(client).forEach(widget => {
-                if (widget && typeof widget.callback === 'function') {
-                  widget.callback(token);
-                }
-              });
-            });
-          }
-        } catch (_) {}
-      }
+      const ta = document.querySelector('#g-recaptcha-response, [name="g-recaptcha-response"]');
+      if (ta) { ta.style.display = 'block'; ta.value = token; ta.dispatchEvent(new Event('change', { bubbles: true })); }
+      try {
+        const clients = window.___grecaptcha_cfg && window.___grecaptcha_cfg.clients;
+        if (clients) Object.values(clients).forEach(c => Object.values(c).forEach(w => { if (w && typeof w.callback === 'function') w.callback(token); }));
+      } catch (_) {}
     }
-    // hCaptcha
     if (type === 'hcaptcha') {
-      const textarea = document.querySelector('[name="h-captcha-response"], #h-captcha-response');
-      if (textarea) {
-        textarea.style.display = 'block';
-        textarea.value = token;
-        textarea.dispatchEvent(new Event('change', { bubbles: true }));
-      }
+      const ta = document.querySelector('[name="h-captcha-response"], #h-captcha-response');
+      if (ta) { ta.style.display = 'block'; ta.value = token; ta.dispatchEvent(new Event('change', { bubbles: true })); }
     }
-    // Turnstile
     if (type === 'turnstile') {
-      const input = document.querySelector('[name="cf-turnstile-response"]');
-      if (input) {
-        input.value = token;
-        input.dispatchEvent(new Event('change', { bubbles: true }));
-      }
+      const inp = document.querySelector('[name="cf-turnstile-response"]');
+      if (inp) { inp.value = token; inp.dispatchEvent(new Event('change', { bubbles: true })); }
     }
   }, { type: detected.type, token });
 
-  log('✅ Token injected into page');
+  log('✅ Token injected');
   return { token, type: detected.type, sitekey: detected.sitekey };
 }
 
 // ─── LAUNCH ───────────────────────────────────────────────────────────────────
 
 /**
- * Launch a human-like browser session
- * @param {Object} opts
- * @param {boolean} opts.mobile    - Use iPhone 15 (default: true)
- * @param {boolean} opts.useProxy  - Use residential proxy (default: true)
- * @param {boolean} opts.headless  - Headless mode (default: true)
- * @param {string}  opts.country   - Proxy country code: 'ro','us','de','gb','fr'... (default: env HB_PROXY_COUNTRY or 'ro')
- * @param {string}  opts.session   - Sticky session ID / Decodo port (default: random unique)
+ * Launch a human-like browser with residential proxy and device fingerprint
+ *
+ * @param {Object}  opts
+ * @param {string}  opts.country   — 'ro'|'us'|'gb'|'de'|'nl'|'jp'|'fr'|'ca'|'au'|'sg' (default: 'ro')
+ * @param {boolean} opts.mobile    — iPhone 15 Pro (true) or Desktop Chrome (false). Default: true
+ * @param {boolean} opts.useProxy  — Enable residential proxy. Default: true
+ * @param {boolean} opts.headless  — Headless mode. Default: true
+ * @param {string}  opts.session   — Sticky session ID / Decodo port (unique IP per value)
+ *
+ * @returns {{ browser, ctx, page, humanClick, humanMouseMove, humanType, humanScroll, humanRead, sleep, rand }}
  */
 async function launchHuman(opts = {}) {
   const {
-    mobile = true,
+    country  = null,
+    mobile   = true,
     useProxy = true,
     headless = true,
-    country = null,
-    session = null,
+    session  = null,
   } = opts;
 
-  const device = mobile ? IPHONE15 : DESKTOP_RO;
+  const cty = country || process.env.HB_PROXY_COUNTRY || 'ro';
+
+  // Auto-fetch trial credentials if no proxy is configured
+  if (useProxy && !process.env.HB_PROXY_USER && !process.env.PROXY_USER && !process.env.HB_PROXY_SERVER) {
+    try {
+      await getTrial();
+    } catch (e) {
+      console.warn('⚠️  Could not fetch trial credentials:', e.message);
+      console.warn('   Get credentials at: https://humanbrowser.dev');
+    }
+  }
+
+  const device = buildDevice(mobile, cty);
+  const meta   = COUNTRY_META[cty.toLowerCase()] || COUNTRY_META.ro;
+  const proxy  = useProxy ? makeProxy(session, cty) : null;
 
   const browser = await chromium.launch({
     headless,
@@ -555,7 +481,7 @@ async function launchHuman(opts = {}) {
       '--no-sandbox',
       '--disable-setuid-sandbox',
       '--ignore-certificate-errors',
-      '--disable-blink-features=AutomationControlled', // Hide webdriver flag!
+      '--disable-blink-features=AutomationControlled',
       '--disable-features=IsolateOrigins,site-per-process',
       '--disable-web-security',
     ],
@@ -566,109 +492,165 @@ async function launchHuman(opts = {}) {
     ignoreHTTPSErrors: true,
     permissions: ['geolocation', 'notifications'],
   };
-
-  if (useProxy) {
-    // Each unique session = unique sticky IP. Same session = same IP.
-    ctxOpts.proxy = makeProxy(session, country);
-  }
+  if (proxy) ctxOpts.proxy = proxy;
 
   const ctx = await browser.newContext(ctxOpts);
 
   // Anti-detection: override navigator properties
-  await ctx.addInitScript(() => {
-    // Hide webdriver
-    Object.defineProperty(navigator, 'webdriver', { get: () => false });
-    
-    // Fix plugins (mobile has none, that's normal for Safari)
-    if (!navigator.plugins.length) {
-      // Leave as-is for mobile
+  await ctx.addInitScript((m) => {
+    Object.defineProperty(navigator, 'webdriver',           { get: () => false });
+    Object.defineProperty(navigator, 'maxTouchPoints',      { get: () => m.mobile ? 5 : 0 });
+    Object.defineProperty(navigator, 'platform',            { get: () => m.mobile ? 'iPhone' : 'Win32' });
+    Object.defineProperty(navigator, 'hardwareConcurrency', { get: () => m.mobile ? 6 : 8 });
+    Object.defineProperty(navigator, 'language',            { get: () => m.locale });
+    Object.defineProperty(navigator, 'languages',           { get: () => [m.locale, 'en'] });
+    if (m.mobile) {
+      Object.defineProperty(screen, 'width',       { get: () => 393 });
+      Object.defineProperty(screen, 'height',      { get: () => 852 });
+      Object.defineProperty(screen, 'availWidth',  { get: () => 393 });
+      Object.defineProperty(screen, 'availHeight', { get: () => 852 });
     }
-    
-    // Override chrome object (not present in Safari)
-    // delete window.chrome; // Not needed for iPhone UA
-    
-    // Realistic touch events for iOS
-    Object.defineProperty(navigator, 'maxTouchPoints', { get: () => 5 });
-    
-    // Platform
-    Object.defineProperty(navigator, 'platform', { get: () => 'iPhone' });
-    
-    // Language
-    Object.defineProperty(navigator, 'language', { get: () => 'ro-RO' });
-    Object.defineProperty(navigator, 'languages', { get: () => ['ro-RO', 'ro', 'en-US', 'en'] });
-    
-    // Screen (iPhone 15 Pro)
-    Object.defineProperty(screen, 'width', { get: () => 393 });
-    Object.defineProperty(screen, 'height', { get: () => 852 });
-    Object.defineProperty(screen, 'availWidth', { get: () => 393 });
-    Object.defineProperty(screen, 'availHeight', { get: () => 852 });
-    
-    // Hardware concurrency (iPhone has 6 cores)
-    Object.defineProperty(navigator, 'hardwareConcurrency', { get: () => 6 });
-    
-    // Memory (4GB iPhone)
-    // Object.defineProperty(navigator, 'deviceMemory', { get: () => 4 }); // Safari doesn't expose this
-    
-    // Connection (LTE/5G)
     if (navigator.connection) {
-      Object.defineProperty(navigator.connection, 'effectiveType', { get: () => '4g' });
-      Object.defineProperty(navigator.connection, 'rtt', { get: () => rand(30, 80) });
+      try {
+        Object.defineProperty(navigator.connection, 'effectiveType', { get: () => '4g' });
+      } catch (_) {}
     }
-    
-    function rand(a, b) { return Math.floor(Math.random() * (b - a + 1)) + a; }
-  });
+  }, { mobile, locale: meta.locale });
 
   const page = await ctx.newPage();
 
-  // Add realistic touch simulation for mobile
-  if (mobile) {
-    await page.addInitScript(() => {
-      // Simulate touch
-      window.ontouchstart = null;
-      window.ontouchmove = null;
-      window.ontouchend = null;
-    });
-  }
-
   return { browser, ctx, page, humanClick, humanMouseMove, humanType, humanScroll, humanRead, sleep, rand };
 }
 
-// ─── EXPORT ───────────────────────────────────────────────────────────────────
-module.exports = { 
-  launchHuman,
-  getTrial,
+// ─── SHADOW DOM UTILITIES ─────────────────────────────────────────────────────
+
+/**
+ * Query an element inside shadow DOM (any depth).
+ * Use when page.$() returns null but element is visible on screen.
+ */
+async function shadowQuery(page, selector) {
+  return page.evaluate((sel) => {
+    function q(root, s) {
+      const el = root.querySelector(s); if (el) return el;
+      for (const n of root.querySelectorAll('*')) if (n.shadowRoot) { const f = q(n.shadowRoot, s); if (f) return f; }
+    }
+    return q(document, sel);
+  }, selector);
+}
+
+/**
+ * Fill an input inside shadow DOM.
+ * Uses native input setter to trigger React/Angular onChange properly.
+ */
+async function shadowFill(page, selector, value) {
+  await page.evaluate(({ sel, val }) => {
+    function q(root, s) {
+      const el = root.querySelector(s); if (el) return el;
+      for (const n of root.querySelectorAll('*')) if (n.shadowRoot) { const f = q(n.shadowRoot, s); if (f) return f; }
+    }
+    const el = q(document, sel);
+    if (!el) throw new Error('shadowFill: not found: ' + sel);
+    const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+    setter.call(el, val);
+    el.dispatchEvent(new Event('input',  { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+  }, { sel: selector, val: value });
+}
+
+/**
+ * Click a button by text label, searching through shadow DOM.
+ */
+async function shadowClickButton(page, buttonText) {
+  await page.evaluate((text) => {
+    function find(root) {
+      for (const b of root.querySelectorAll('button')) if (b.textContent.trim() === text) return b;
+      for (const n of root.querySelectorAll('*')) if (n.shadowRoot) { const f = find(n.shadowRoot); if (f) return f; }
+    }
+    const btn = find(document);
+    if (!btn) throw new Error('shadowClickButton: not found: ' + text);
+    btn.click();
+  }, buttonText);
+}
+
+/**
+ * Dump all interactive elements including inside shadow roots.
+ * Use for debugging when form elements aren't found by standard selectors.
+ */
+async function dumpInteractiveElements(page) {
+  return page.evaluate(() => {
+    const res = [];
+    function collect(root) {
+      for (const el of root.querySelectorAll('input,textarea,button,select,[contenteditable]')) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0)
+          res.push({ tag: el.tagName, name: el.name || '', id: el.id || '', type: el.type || '', text: el.textContent?.trim().slice(0, 25) || '', placeholder: el.placeholder?.slice(0, 25) || '' });
+      }
+      for (const n of root.querySelectorAll('*')) if (n.shadowRoot) collect(n.shadowRoot);
+    }
+    collect(document);
+    return res;
+  });
+}
+
+// ─── RICH TEXT EDITOR UTILITIES ───────────────────────────────────────────────
+
+/**
+ * Paste text into a Lexical/ProseMirror/Quill/Draft.js rich text editor.
+ * Uses clipboard API — works where keyboard.type() and fill() fail.
+ *
+ * Common selectors:
+ *   '[data-lexical-editor]'       — Reddit, Meta apps
+ *   '.public-DraftEditor-content' — Draft.js (Twitter, Quora)
+ *   '.ql-editor'                  — Quill
+ *   '.ProseMirror'                — Linear, Confluence
+ *   '[contenteditable="true"]'    — generic
+ */
+async function pasteIntoEditor(page, editorSelector, text) {
+  const el = await page.$(editorSelector);
+  if (!el) throw new Error('pasteIntoEditor: editor not found: ' + editorSelector);
+  await el.click();
+  await sleep(300);
+  await page.evaluate((t) => {
+    const ta = document.createElement('textarea');
+    ta.value = t;
+    document.body.appendChild(ta);
+    ta.select();
+    document.execCommand('copy');
+    document.body.removeChild(ta);
+  }, text);
+  await page.keyboard.press('Control+a');
+  await sleep(100);
+  await page.keyboard.press('Control+v');
+  await sleep(500);
+}
+
+// ─── EXPORTS ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  launchHuman, getTrial,
   humanClick, humanMouseMove, humanType, humanScroll, humanRead,
   solveCaptcha,
-  sleep, rand,
-  PROXY, makeProxy, IPHONE15, DESKTOP_RO
+  shadowQuery, shadowFill, shadowClickButton, dumpInteractiveElements,
+  pasteIntoEditor,
+  makeProxy, buildDevice,
+  sleep, rand, COUNTRY_META,
 };
 
 // ─── QUICK TEST ───────────────────────────────────────────────────────────────
 if (require.main === module) {
+  const country = process.argv[2] || 'ro';
+  console.log(`🧪 Testing Human Browser v4.0.0 — country: ${country.toUpperCase()}\n`);
   (async () => {
-    console.log('🧪 Testing human browser (iPhone 15, Romania)...\n');
-    
-    const { browser, page, humanScroll, humanRead } = await launchHuman({ mobile: true });
-    
+    const { browser, page } = await launchHuman({ country, mobile: true });
     await page.goto('https://ipinfo.io/json', { waitUntil: 'domcontentloaded', timeout: 30000 });
     const info = JSON.parse(await page.textContent('body'));
-    console.log(`✅ IP: ${info.ip}`);
+    console.log(`✅ IP:      ${info.ip}`);
     console.log(`✅ Country: ${info.country} (${info.city})`);
-    console.log(`✅ Org: ${info.org}`);
-    console.log(`✅ Timezone: ${info.timezone}`);
-    
-    // Test UA
+    console.log(`✅ Org:     ${info.org}`);
+    console.log(`✅ TZ:      ${info.timezone}`);
     const ua = await page.evaluate(() => navigator.userAgent);
-    console.log(`\n✅ User-Agent: ${ua.slice(0, 80)}...`);
-    
-    const platform = await page.evaluate(() => navigator.platform);
-    const lang = await page.evaluate(() => navigator.language);
-    const touch = await page.evaluate(() => navigator.maxTouchPoints);
-    console.log(`✅ Platform: ${platform}`);
-    console.log(`✅ Language: ${lang}`);
-    console.log(`✅ Touch points: ${touch}`);
-    
+    console.log(`✅ UA:      ${ua.slice(0, 80)}...`);
     await browser.close();
-    console.log('\n🎉 All good! Browser is fully configured.');
+    console.log('\n🎉 Human Browser v4.0.0 is ready.');
   })().catch(console.error);
 }