capiumbrowser 1.2.0 → 1.2.1

package/README.md

@@ -66,6 +66,7 @@ await browser.close();
 - [Install](#install) · [Why Capium](#why-capium) · [Licensing & tiers](#licensing)
 - [What a persona reads](#what-a-persona-reads) · [How it works](#how-it-works)
 - [API](#api) · [Options](#options) · [Personas & seeds](#personas--seeds) · [Fingerprint switches](#fingerprint-switches)
+- [Browser and mobile profiles](#browser-and-mobile-profiles)
 - [Human behavior](#human-behavior) · [Proxies & geo](#proxies--geo) · [Fonts](#fonts)
 - [Framework integrations](#framework-integrations) · [Deployment](#deployment) · [Platforms](#platforms)
 - [CLI](#cli--environment) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [Security](#security) · [License](#license)
@@ -340,7 +341,9 @@ Python SDK, in camelCase.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `seed` | `number` \| `null` | `null` | Persona seed → a complete coherent device. `null` = fresh random seed each launch. The range selects the OS family (see [Personas & seeds](#personas--seeds)). |
-| `platform` | `string` | `"windows"` | Spoofed OS: `"windows"` \| `"macos"` \| `"linux"`. Sets `--fingerprint-platform` and picks the seed range if you didn't. |
+| `platform` | `string` | `"windows"` | OS profile: `"windows"` \| `"macos"` \| `"linux"` \| `"android"` \| `"ios"`. Mobile profiles are opt-in. |
+| `browserBrand` | `string` | `"chrome"` | Desktop profile: `chrome`, `edge`, `opera`, `vivaldi`. |
+| `mobileDevice` | `string` | seed/default | Phone catalog ID; requires `android` or `ios`. |
 | `headless` | `boolean` | `false` | Headed is recommended (reads cleaner). On a server, run headed under Xvfb. |
 | `stealthArgs` | `boolean` | `true` | Apply the default coherent fingerprint flags. Set `false` to build the whole command line yourself via `args`. |
 | `args` | `string[]` | — | Extra raw Chrome flags appended verbatim (see [Fingerprint switches](#fingerprint-switches)). |
@@ -442,6 +445,43 @@ Full runnable version (personas, persistent profiles, a fleet, proxy+geo, full c
 
 ---
 
+## Browser and mobile profiles
+
+CapiumBrowser 1.2.1 supports desktop Chrome, Edge, Opera and Vivaldi identity
+profiles, plus opt-in Android and iPhone profiles on Windows x64, macOS arm64
+and Linux x64. Chrome remains the default.
+
+| Profile | Python | Node.js |
+| --- | --- | --- |
+| Desktop browser | `browser_brand="edge"` (also `chrome`, `opera`, `vivaldi`) | `browserBrand: 'edge'` |
+| Android phone | `platform="android", mobile_device="pixel-9"` | `platform: 'android', mobileDevice: 'pixel-9'` |
+| iPhone 16 | `platform="ios", mobile_device="iphone-16"` | `platform: 'ios', mobileDevice: 'iphone-16'` |
+
+Android includes Pixel 7/8/9 families and Samsung Galaxy A55. Omit the Android
+device to retain the original seed selection; iOS defaults to iPhone 16. Mobile
+profiles set the mobile layout and identity while leaving desktop defaults intact.
+These are experimental desktop emulation profiles: they do not install Android
+or iOS, reproduce WebKit, or certify physical-phone fingerprints. Android Chrome
+and Chrome iOS are the supported mobile browser profiles; arbitrary app/WebView
+UAs are outside these presets.
+
+Desktop profiles use verified browser/Chromium version pairs: Edge 155/155,
+Opera 137/153 and Vivaldi 8.2/152. Vivaldi follows its usual Chrome branding.
+Capium's engine remains Chromium 155; vendor-specific features are not emulated.
+A version catalog is not an older browser engine. Native compatibility checks
+reject binaries that do not implement the selected profile.
+
+```js
+const { launchContext } = require('capiumbrowser');
+
+const { browser, page } = await launchContext({
+  seed: 200123, platform: 'ios', mobileDevice: 'iphone-16',
+});
+// Android: platform: 'android', mobileDevice: 'pixel-9'
+// Desktop Edge: platform: 'windows', browserBrand: 'edge'
+await browser.close();
+```
+
 ## Fingerprint switches
 
 The SDK sets the essentials from `seed`/`platform`. Everything below is available for precise control —
@@ -670,13 +710,12 @@ launches **headed**, which reads cleaner than headless.
 | Linux arm64 | `linux-arm64` | Declared in the manifest; not yet published or covered by the three-host audit |
 
 The SDK auto-detects your host and downloads the matching tag; macOS Intel and Windows ARM are **not**
-published and throw a clear error. The **1.2.0** manifest selects **Chromium 155.0.8059.39, revision 1** on the three
-supported hosts. This release is prepared as a draft; downloads become available when the browser
-artifacts are published. Linux arm64 remains unpublished.
+published and throw a clear error. The **1.2.1** manifest selects **Chromium 155.0.8059.39, revision 2** on the three
+supported hosts. Browser downloads are available with a valid license. Linux arm64 remains unpublished.
 
 ---
 
-The 1.2.0 launch APIs wait for the packaged browser's licensing decision before
+The launch APIs wait for the packaged browser's licensing decision before
 returning a handle. Invalid keys raise a typed error during launch.
 
 ## CLI & environment

package/index.d.ts

@@ -9,7 +9,11 @@
  *     const browser = (await launch({ seed: 42 })) as unknown as Browser;
  */
 
-export type Platform = 'windows' | 'macos' | 'linux';
+/** Mobile profiles emulate identity/layout on the supported desktop hosts. */
+export type Platform = 'windows' | 'macos' | 'linux' | 'android' | 'ios';
+export type AndroidDevice = 'pixel-7' | 'pixel-8' | 'pixel-8-pro' | 'pixel-8a' | 'pixel-9' |
+  'samsung-galaxy-a55' | 'pixel-9-pro' | 'pixel-9-pro-xl';
+export type IOSDevice = 'iphone-16';
 
 export interface ProxySpec {
   /** "scheme://host:port" (http, https, socks5). */
@@ -21,10 +25,14 @@ export interface ProxySpec {
 }
 
 export interface LaunchOptions {
+  /** Desktop identity profile; vendor features are not emulated. */
+  browserBrand?: 'chrome' | 'edge' | 'opera' | 'vivaldi' | null;
   /** Identity seed (a stable, coherent device per seed). Random if omitted. */
   seed?: number | null;
   /** The spoofed OS persona. Default "windows". */
   platform?: Platform;
+  /** Phone catalog ID. Android uses the original seed mapping; iOS defaults to iPhone 16. */
+  mobileDevice?: AndroidDevice | IOSDevice | null;
   /** Default false (a windowed browser is the coherent persona default). */
   headless?: boolean;
   /** "http://user:pass@host:port" | "socks5://host:port" | ProxySpec. */
@@ -102,7 +110,8 @@ export function status(licenseKey?: string | null, licenseServer?: string | null
 
 export namespace config {
   function getDefaultStealthArgs(seed?: number | null, platform?: Platform,
-    screen?: [number, number] | null): string[];
+    screen?: [number, number] | null, mobileDevice?: AndroidDevice | null,
+    browserBrand?: 'chrome' | 'edge' | 'opera' | 'vivaldi' | null): string[];
   function newSeed(): number;
   function findBinary(binary?: string | null): string;
 }

package/lib/android-phones.json

@@ -0,0 +1,99 @@
+{
+  "schema_version": 2,
+  "minimum_release_year": 2022,
+  "browser": "chrome",
+  "status": "experimental-emulation",
+  "gpu_policy": "host",
+  "hardware_policy": "host",
+  "physical_device_validation": "pending",
+  "default_profile_ids": [
+    "pixel-7",
+    "pixel-8",
+    "pixel-8-pro",
+    "pixel-8a",
+    "pixel-9"
+  ],
+  "sources": [
+    "https://support.google.com/pixelphone/answer/7158570?hl=en",
+    "https://news.samsung.com/global/samsung-galaxy-a55-5g-and-galaxy-a35-5g-awesome-innovations-and-security-engineered-for-everyone",
+    "https://www.samsung.com/ie/business/smartphones/galaxy-a/galaxy-a55-5g-awesome-navy-256gb-sm-a556bzkceub/",
+    "https://chromium.googlesource.com/devtools/devtools-frontend/+/cd7bfad9bba968ac23ba67e538f9e1d499991d25/front_end/models/emulation/EmulatedDevices.ts"
+  ],
+  "profiles": [
+    {
+      "id": "pixel-7",
+      "model": "Pixel 7",
+      "release_year": 2022,
+      "platform_version": "13",
+      "width": 412,
+      "height": 915,
+      "dpr": 2.625
+    },
+    {
+      "id": "pixel-8",
+      "model": "Pixel 8",
+      "release_year": 2023,
+      "platform_version": "14",
+      "width": 412,
+      "height": 915,
+      "dpr": 2.625
+    },
+    {
+      "id": "pixel-8-pro",
+      "model": "Pixel 8 Pro",
+      "release_year": 2023,
+      "platform_version": "14",
+      "width": 448,
+      "height": 997,
+      "dpr": 3.0
+    },
+    {
+      "id": "pixel-8a",
+      "model": "Pixel 8a",
+      "release_year": 2024,
+      "platform_version": "14",
+      "width": 412,
+      "height": 915,
+      "dpr": 2.625
+    },
+    {
+      "id": "pixel-9",
+      "model": "Pixel 9",
+      "release_year": 2024,
+      "platform_version": "14",
+      "width": 412,
+      "height": 924,
+      "dpr": 2.625
+    },
+    {
+      "id": "samsung-galaxy-a55",
+      "model": "SM-A556B",
+      "display_name": "Samsung Galaxy A55",
+      "release_year": 2024,
+      "platform_version": "14",
+      "width": 360,
+      "height": 800,
+      "dpr": 2.25,
+      "geometry_status": "devtools-emulation-only",
+      "geometry_note": "These Chromium preset dimensions/DPR do not directly map to the published 1080x2340 panel; physical Chrome capture required."
+    },
+    {
+      "id": "pixel-9-pro",
+      "model": "Pixel 9 Pro",
+      "release_year": 2024,
+      "platform_version": "14",
+      "width": 427,
+      "height": 952,
+      "dpr": 3.0
+    },
+    {
+      "id": "pixel-9-pro-xl",
+      "model": "Pixel 9 Pro XL",
+      "release_year": 2024,
+      "platform_version": "14",
+      "width": 448,
+      "height": 997,
+      "dpr": 3.0
+    }
+  ]
+}

package/lib/browser-brands.json

@@ -0,0 +1,47 @@
+{
+  "schema_version": 1,
+  "verified_on": "2026-10-10",
+  "engine_version": "155.0.8059.39",
+  "scope": "Desktop UA and Client Hints profiles; does not install vendor engines or features.",
+  "profiles": [
+    {
+      "brand": "edge",
+      "product_version": "155.0.4283.45",
+      "chromium_version": "155.0.8059.40",
+      "hint_brand": "Microsoft Edge",
+      "ua_suffix": " Edg/",
+      "ua_version": "155.0.0.0",
+      "sources": [
+        "https://edgeupdates.microsoft.com/api/products?view=enterprise"
+      ],
+      "measurement": "Stock Edge 155 Windows and Linux owned-origin captures"
+    },
+    {
+      "brand": "opera",
+      "product_version": "137.0.6036.39",
+      "chromium_version": "153.0.8010.55",
+      "hint_brand": "Opera",
+      "ua_suffix": " OPR/",
+      "ua_version": "137.0.0.0",
+      "sources": [
+        "https://blogs.opera.com/desktop/changelog-for-137/",
+        "https://blogs.opera.com/desktop/2026/10/opera-137-stable/"
+      ],
+      "measurement": "Stock Opera 137 Linux owned-origin capture"
+    },
+    {
+      "brand": "vivaldi",
+      "product_version": "8.2.4133.84",
+      "chromium_version": "152.0.7977.160",
+      "hint_brand": "Google Chrome",
+      "ua_suffix": "",
+      "ua_version": "",
+      "sources": [
+        "https://vivaldi.com/blog/minor-update-nine-8-2/",
+        "https://vivaldi.com/blog/desktop/",
+        "https://help.vivaldi.com/developers/web/vivaldi-user-agent-and-client-hints-user-agent/"
+      ],
+      "measurement": "Stock Vivaldi 8.2 Linux owned-origin capture; default branding only, partner-site exceptions excluded"
+    }
+  ]
+}

package/lib/channels.json

@@ -6,28 +6,28 @@
     "stable": {
       "windows-x64": {
         "version": "155.0.8059.39",
-        "revision": 1,
-        "sha256": "d973e2460ce05e99f7e5c1dddc319ae96733434d9986dadc4cec5bac1c2597fb",
+        "revision": 2,
+        "sha256": "25ef98b8713c2c9fb62615b4c9aa0d7a3bd20c76320ec3d99e848775b1d4fdd6",
         "published": true,
         "license_status_protocol": 1
       },
       "macos-arm64": {
         "version": "155.0.8059.39",
-        "revision": 1,
-        "sha256": "f07d54b88feb6644388196d6b91c9787592c1f6e07a8122344f47faed76b9262",
+        "revision": 2,
+        "sha256": "2c39538576a8c5f63b39ac1f09cdb1cc5f7d2b6899ed7625752c6c4c2737a90f",
         "published": true,
         "license_status_protocol": 1
       },
       "linux-x64": {
         "version": "155.0.8059.39",
-        "revision": 1,
-        "sha256": "a15cd395e1f8b792d9539c8284edcd589c6b91ef77f8b1fa5ea408f1f220b540",
+        "revision": 2,
+        "sha256": "87889050d6a1e46a8aabe4800f8fff5e474a07cd23e22a66f79b830f5544487c",
         "published": true,
         "license_status_protocol": 1
       },
       "linux-arm64": {
         "version": "155.0.8059.39",
-        "revision": 1,
+        "revision": 2,
         "sha256": null,
         "published": false
       }

package/lib/config.js

@@ -48,13 +48,35 @@ function hasScreenOverride(extra) {
  * Return the default per-launch fingerprint flags.
  *
  * seed:     int identity seed (a stable, coherent device per seed). Random if null.
- * platform: "windows" | "macos" | "linux" -- the spoofed OS persona.
+ * platform: "windows" | "macos" | "linux" | "android" | "ios" -- the OS persona.
+ * mobileDevice: optional Android catalog ID; omitted keeps the seed modulo 5 mapping.
  * screen:   null uses the binary's seeded screen and DPR. Development 155 defaults
  *           vary within 1920x1080. Headless starts with an 800x600 window; its screen
  *           remains independent of the viewport. An explicit [w,h] overrides the screen
  *           and startup window, including sizes above the default cap.
  */
-function getDefaultStealthArgs(seed = null, platform = 'windows', screen = null) {
+function getDefaultStealthArgs(seed = null, platform = 'windows', screen = null, mobileDevice = null, browserBrand = null) {
+  const desktopArgs = require('./desktop').brandArgs(browserBrand, platform);
+  if (mobileDevice !== null && mobileDevice !== undefined && !['android', 'ios'].includes(platform)) {
+    throw new Error("mobileDevice requires platform: 'android' or 'ios'");
+  }
+  if (['android', 'ios'].includes(platform)) {
+    const p = require('./mobile').mobileProfile(seed, mobileDevice, platform);
+    const [sw, sh] = screen ? screen.map(v => Math.trunc(Number(v))) : [p.width, p.height];
+    return [
+      `--fingerprint=${seed}`, `--fingerprint-platform=${platform}`,
+      ...(mobileDevice !== null && mobileDevice !== undefined ? [`--fingerprint-mobile-device=${mobileDevice}`] : []),
+      '--fingerprint-allow-3p-cookies', '--disable-features=TrackingProtection3pcd',
+      '--blink-settings=primaryHoverType=0,availableHoverTypes=0,' +
+        'primaryPointerType=2,availablePointerTypes=2,maxTouchPoints=5,' +
+        'viewportEnabled=true,viewportMetaEnabled=true,shrinksViewportContentToFit=true',
+      '--touch-events=enabled', '--enable-viewport',
+      '--no-first-run', '--no-default-browser-check', '--fingerprint-noise=false',
+      `--window-size=${sw},${sh}`,
+      ...(platform === 'ios' ? [`--user-agent=${p.user_agent}`, '--capium-preserve-user-agent'] : []),
+      ...(screen ? [`--fingerprint-screen-width=${sw}`, `--fingerprint-screen-height=${sh}`] : []),
+    ];
+  }
   const args = [];
   if (seed !== null && seed !== undefined) {
     const s = Math.trunc(Number(seed));
@@ -106,7 +128,7 @@ function getDefaultStealthArgs(seed = null, platform = 'windows', screen = null)
     args.push(`--fingerprint-screen-width=${sw}`);
     args.push(`--fingerprint-screen-height=${sh}`);
   }
-  return args;
+  return args.concat(desktopArgs);
 }
 
 /** A fresh random identity seed. */

package/lib/desktop.js

@@ -0,0 +1,68 @@
+'use strict';
+const catalog = require('./browser-brands.json');
+const profiles = new Map(catalog.profiles.map(p => [p.brand, p]));
+
+function normalizeBrand(brand) {
+  if (brand === null || brand === undefined) return 'chrome';
+  if (typeof brand !== 'string' || !['chrome', ...profiles.keys()].includes(brand.toLowerCase())) {
+    throw new Error('browserBrand must be chrome, edge, opera, or vivaldi');
+  }
+  return brand.toLowerCase();
+}
+
+function brandArgs(brand, platform) {
+  brand = normalizeBrand(brand);
+  if (brand === 'chrome') return [];
+  if (!['windows', 'macos', 'linux'].includes(platform)) throw new Error('browserBrand requires a desktop platform');
+  return [`--fingerprint-brand=${brand}`];
+}
+
+function validateLaunch(brand, platform, binary, extra, stealthArgs) {
+  if (!brandArgs(brand, platform).length) return;
+  if (!stealthArgs) throw new Error('browserBrand requires stealthArgs: true');
+  const conflicts = ['--user-agent', '--fingerprint-brand', '--fingerprint-brand-version', '--fingerprint-platform'];
+  if ((extra || []).some(arg => typeof arg === 'string' && conflicts.some(key => arg === key || arg.startsWith(key + '=')))) {
+    throw new Error('browserBrand uses the verified catalog; conflicting identity overrides are not supported');
+  }
+}
+
+async function engineProbe(expected) {
+  const h = await navigator.userAgentData?.getHighEntropyValues(['fullVersionList', 'uaFullVersion']);
+  if (!h) return false;
+  const chromium = expected.chromium_version;
+  const product = expected.hint_brand === 'Google Chrome' ? chromium : expected.product_version;
+  const expectedBrands = { Chromium: chromium, [expected.hint_brand]: product };
+  const full = Object.fromEntries(h.fullVersionList.map(b => [b.brand, b.version]));
+  const low = Object.fromEntries(h.brands.map(b => [b.brand, b.version]));
+  return h.uaFullVersion === product && h.mobile === false &&
+    Object.entries(expectedBrands).every(([brand, version]) => full[brand] === version && low[brand] === version.split('.')[0]) &&
+    ['Google Chrome', 'Microsoft Edge', 'Opera', 'Vivaldi', 'Chromium'].every(brand => !(brand in full) || brand in expectedBrands) &&
+    navigator.userAgent.includes('Chrome/' + chromium.split('.')[0] + '.0.0.0') &&
+    (!expected.ua_suffix || navigator.userAgent.endsWith(expected.ua_suffix + expected.ua_version)) &&
+    (expected.brand !== 'vivaldi' || !navigator.userAgent.includes('Vivaldi/'));
+}
+
+function profile(brand) { return { ...profiles.get(normalizeBrand(brand)) }; }
+
+async function requireEngine(context, brand) {
+  if (normalizeBrand(brand) === 'chrome') return;
+  const page = await context.newPage();
+  try {
+    await page.route('**/*', route => route.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html>' }));
+    await page.goto('https://capium-desktop-preview.invalid/', { waitUntil: 'domcontentloaded' });
+    if (!await page.evaluate(engineProbe, profile(brand))) throw new Error('This binary does not support the verified desktop browser-brand mappings; use Capium 1.2.1 revision 2 or later');
+  } finally { await page.close(); }
+}
+
+async function requirePuppeteerEngine(browser, brand) {
+  if (normalizeBrand(brand) === 'chrome') return;
+  const page = await browser.newPage();
+  try {
+    await page.setRequestInterception(true);
+    page.on('request', request => request.respond({ status: 200, contentType: 'text/html', body: '<!doctype html>' }));
+    await page.goto('https://capium-desktop-preview.invalid/', { waitUntil: 'domcontentloaded' });
+    if (!await page.evaluate(engineProbe, profile(brand))) throw new Error('This binary does not support the verified desktop browser-brand mappings; use Capium 1.2.1 revision 2 or later');
+  } finally { await page.close(); }
+}
+
+module.exports = { normalizeBrand, brandArgs, validateLaunch, profile, engineProbe, requireEngine, requirePuppeteerEngine };

package/lib/ios-phones.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": 1,
+  "status": "experimental-emulation",
+  "minimum_release_year": 2022,
+  "physical_device_validation": "pending",
+  "profiles": [
+    {
+      "id": "iphone-16",
+      "model": "iPhone 16",
+      "release_year": 2024,
+      "os_version": "26.6.1",
+      "browser_version": "155.0.8059.37",
+      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/155.0.8059.37 Mobile/15E148 Safari/604.1",
+      "width": 393,
+      "height": 852,
+      "dpr": 3
+    }
+  ]
+}

package/lib/launch-common.js

@@ -40,13 +40,13 @@ function proxyAndGeoArgs(spec, geoipOn) {
 }
 
 function buildArgs({ seed, platform, stealthArgs, timezone, locale, extensionPaths, extra,
-  headless = false }) {
+  headless = false, mobileDevice = null, browserBrand = null }) {
   let args = [];
   if (stealthArgs) {
-    args = args.concat(config.getDefaultStealthArgs(seed, platform));
+    args = args.concat(config.getDefaultStealthArgs(seed, platform, null, mobileDevice, browserBrand));
     // Keep the engine's seeded screen. Use initial window bounds only when
     // the caller has not provided screen/window flags.
-    if (headless && !config.hasScreenOverride(extra)) {
+    if (headless && !['android', 'ios'].includes(platform) && !config.hasScreenOverride(extra)) {
       args = args.concat(config.getHeadlessDefaultArgs());
     }
   }

package/lib/license-readiness.js

@@ -29,7 +29,10 @@ async function wait(binary, statusPath, timeoutMs = 30000, signal = null) {
     try {
       if (fs.readFileSync(statusPath, 'utf8').trim() === '0\nCAPIUM_LICENSE_READY') return;
     } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
+      // The native writer briefly locks this owned file on Windows. Keep
+      // waiting for a real decision; unreadable status is never readiness.
+      if (!['ENOENT', 'EBUSY'].includes(error.code) &&
+          !(process.platform === 'win32' && ['EACCES', 'EPERM'].includes(error.code))) throw error;
     }
     if (Date.now() >= deadline) {
       throw new CapiumServerDownError('Timed out waiting for the browser license startup decision');

package/lib/mobile.js

@@ -0,0 +1,104 @@
+'use strict';
+
+// Shared with the native engine. These are emulation presets, not physical
+// GPU/font/CPU/memory certifications. Desktop defaults never read this catalog.
+const catalog = require('./android-phones.json');
+const profiles = new Map(catalog.profiles.map(p => [p.id, p]));
+const iosProfiles = new Map(require('./ios-phones.json').profiles.map(p => [p.id, p]));
+
+function androidProfile(seed, device = null) {
+  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+    throw new RangeError('Android seed must be an integer from 0 to 4294967295');
+  }
+  if (device === null || device === undefined) {
+    device = catalog.default_profile_ids[seed % catalog.default_profile_ids.length];
+  }
+  if (typeof device !== 'string' || !profiles.has(device)) {
+    throw new RangeError('Unknown Android mobileDevice; choose a catalog ID: ' + [...profiles.keys()].join(', '));
+  }
+  return { ...profiles.get(device) };
+}
+
+function mobileProfile(seed, device = null, platform = 'android') {
+  if (platform === 'android') return androidProfile(seed, device);
+  if (platform !== 'ios') throw new Error("Mobile profiles require platform: 'android' or 'ios'");
+  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+    throw new RangeError('iPhone seed must be an integer from 0 to 4294967295');
+  }
+  device = device === null || device === undefined ? 'iphone-16' : device;
+  if (typeof device !== 'string' || !iosProfiles.has(device)) {
+    throw new RangeError('Unknown iPhone mobileDevice; choose a catalog ID: ' + [...iosProfiles.keys()].join(', '));
+  }
+  return { ...iosProfiles.get(device) };
+}
+
+function contextOptions(seed, options = {}, device = null, platform = 'android') {
+  if (options.userAgent !== undefined && options.userAgent !== null) {
+    throw new Error((platform === 'ios' ? 'iPhone uses its catalog UA; ' :
+      'Android Chrome uses the native engine UA and matching Client Hints; ') +
+      'context userAgent overrides are not supported');
+  }
+  if ('viewport' in options && options.viewport === null) return { ...options };
+  const p = mobileProfile(seed, device, platform);
+  return {
+    viewport: { width: p.width, height: p.height },
+    screen: { width: p.width, height: p.height },
+    deviceScaleFactor: p.dpr, isMobile: true, hasTouch: true,
+    ...options,
+  };
+}
+
+function puppeteerViewport(seed, device = null, platform = 'android') {
+  const p = mobileProfile(seed, device, platform);
+  return { width: p.width, height: p.height, deviceScaleFactor: p.dpr,
+    isMobile: true, hasTouch: true };
+}
+
+function validateLaunch(platform, binary, extra, stealthArgs = true, mobileDevice = null) {
+  if (typeof platform === 'string' && ['android', 'ios'].includes(platform.toLowerCase()) && platform !== platform.toLowerCase()) {
+    throw new Error(`Use platform: '${platform.toLowerCase()}' for the mobile profile`);
+  }
+  if (!['android', 'ios'].includes(platform)) {
+    if (mobileDevice !== null && mobileDevice !== undefined) throw new Error("mobileDevice requires platform: 'android' or 'ios'");
+    return;
+  }
+  if (mobileDevice !== null && mobileDevice !== undefined) mobileProfile(0, mobileDevice, platform);
+  if (!stealthArgs) throw new Error('Mobile profiles require stealthArgs: true to enable their native identity');
+  const conflicts = ['--user-agent=', '--fingerprint-brand=', '--fingerprint-brand-version=',
+    '--fingerprint-platform-version=', '--fingerprint-platform=', '--fingerprint=', '--fingerprint-mobile-device='];
+  if ((extra || []).some(arg => typeof arg === 'string' &&
+    conflicts.some(key => arg.startsWith(key) || arg === key.slice(0, -1)))) {
+    throw new Error('Android preview uses the catalog model/OS and current Chrome; ' +
+      'conflicting identity overrides are not supported');
+  }
+}
+
+// Runs on a fulfilled empty .invalid page for every mobile launch; no network is sent.
+async function engineProbe(expected) {
+  if (expected?.user_agent) {
+    if (navigator.platform !== 'iPhone' || navigator.userAgent !== expected.user_agent ||
+      'userAgentData' in navigator || 'NavigatorUAData' in globalThis || navigator.maxTouchPoints < 1) return false;
+    const gl = document.createElement('canvas').getContext('webgl');
+    const ext = gl?.getExtension('WEBGL_debug_renderer_info');
+    return !!ext && gl.getParameter(ext.UNMASKED_VENDOR_WEBGL) === 'Apple Inc.' &&
+      gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) === 'Apple GPU';
+  }
+  const match = navigator.userAgent.match(/Chrome\/(\d+)\.0\.0\.0 Mobile Safari\//);
+  if (!expected || navigator.platform !== 'Linux armv81' || !match ||
+    !navigator.userAgent.includes('(Linux; Android 10; K)') ||
+    navigator.userAgent.includes('Version/4.0') || !navigator.userAgentData) return false;
+  const ch = await navigator.userAgentData.getHighEntropyValues([
+    'model', 'platformVersion', 'uaFullVersion', 'fullVersionList', 'formFactors',
+    'architecture', 'bitness', 'wow64']);
+  const full = ch.uaFullVersion;
+  const versionsMatch = typeof full === 'string' && full.split('.')[0] === match[1] &&
+    ['Chromium', 'Google Chrome'].every(brand =>
+      ch.brands?.some(item => item.brand === brand && item.version === match[1]) &&
+      ch.fullVersionList?.some(item => item.brand === brand && item.version === full));
+  return versionsMatch && ch.platform === 'Android' && ch.mobile === true &&
+    ch.model === expected.model && ch.platformVersion === expected.platform_version &&
+    ch.architecture === '' && ch.bitness === '' && ch.wow64 === false &&
+    ch.formFactors?.length === 1 && ch.formFactors[0] === 'Mobile';
+}
+
+module.exports = { androidProfile, mobileProfile, contextOptions, puppeteerViewport, validateLaunch, engineProbe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capiumbrowser",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Drop-in stealth browser SDK on top of Playwright or Puppeteer (Capium Chromium).",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Capzy (https://capzy.ai)",

package/playwright.js

@@ -76,24 +76,27 @@ async function resolveBinary(binary, licenseKey) {
  */
 async function prepare(opts) {
   const {
-    seed = null, platform = 'windows', proxy = null, geoip = null, args = null,
+    seed = null, platform = 'windows', mobileDevice = null, browserBrand = null, proxy = null, geoip = null, args = null,
     stealthArgs = true, timezone = null, locale = null, extensionPaths = null,
     binary = null, licenseKey = null, licenseServer = null,
     licenseThroughProxy = false, licensePreflight = true, headless = false,
   } = opts;
+  require('./lib/desktop').validateLaunch(browserBrand, platform, binary, args, stealthArgs);
+  require('./lib/mobile').validateLaunch(platform, binary, args, stealthArgs, mobileDevice);
   if (licensePreflight) license.preflight(licenseKey, licenseServer);
   const { key } = license.effective(licenseKey, licenseServer);
   const binPath = await resolveBinary(binary, key);
   const finalSeed = seed === null || seed === undefined ? config.newSeed() : seed;
   const { launchOptions, args: proxyArgs } = proxyAndGeoArgs(proxy, geoip);
   const launchArgs = proxyArgs.concat(buildArgs({
-    seed: finalSeed, platform, stealthArgs, timezone, locale, extensionPaths, extra: args,
+    seed: finalSeed, platform, mobileDevice, browserBrand, stealthArgs, timezone, locale, extensionPaths, extra: args,
     headless,
   }));
   if (licenseThroughProxy) launchArgs.push('--license-through-proxy');
   const env = license.childEnv(licenseKey, licenseServer);
   const statusPath = newStatusFile(env);
-  return { binPath, finalSeed, launchOptions, launchArgs, env, statusPath };
+  return { binPath, finalSeed, launchOptions, launchArgs, env, statusPath,
+    browserBrand, mobileSeed: ['android', 'ios'].includes(platform) && stealthArgs ? finalSeed : null, mobileDevice, mobilePlatform: platform };
 }
 
 async function throwTranslated(e, statusPath) {
@@ -117,12 +120,12 @@ async function throwTranslated(e, statusPath) {
  */
 async function buildLaunchOptions(opts = {}) {
   const {
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight,
     headless = false, ...rest
   } = opts;
   const prep = await prepare({
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight, headless,
   });
   return {
@@ -140,12 +143,13 @@ async function buildLaunchOptions(opts = {}) {
  * avoid; this closes the plain-launch() path too). An explicit viewport (including a
  * user-passed null) is always honored.
  */
-function applyViewportDefaults(browser) {
+function applyViewportDefaults(browser, mobileSeed = null, mobileDevice = null, mobilePlatform = 'android') {
   for (const method of ['newContext', 'newPage']) {
     const orig = browser[method];
     if (typeof orig !== 'function') continue;
     browser[method] = function (options = {}, ...more) {
-      if (!('viewport' in options)) options = { ...options, viewport: null };
+      if (mobileSeed !== null) options = require('./lib/mobile').contextOptions(mobileSeed, options, mobileDevice, mobilePlatform);
+      else if (!('viewport' in options)) options = { ...options, viewport: null };
       return orig.call(this, options, ...more);
     };
   }
@@ -171,12 +175,12 @@ function applyViewportDefaults(browser) {
  */
 async function launch(opts = {}) {
   const {
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight,
     headless = false, ...rest
   } = opts;
   const prep = await prepare({
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight, headless,
   });
   const pw = requireDriver();
@@ -197,7 +201,33 @@ async function launch(opts = {}) {
   }
   clearStatusFile(prep.statusPath);
   browser._capiumSeed = prep.finalSeed;
-  return applyViewportDefaults(browser);
+  browser._capiumMobile = prep.mobileSeed !== null;
+  applyViewportDefaults(browser, prep.mobileSeed, prep.mobileDevice, prep.mobilePlatform);
+  if (browser._capiumMobile) {
+    try {
+      const context = await browser.newContext();
+      try { await requireMobileEngine(context, prep.mobileDevice, prep.finalSeed, prep.mobilePlatform); } finally { await context.close(); }
+    } catch (e) { await browser.close(); throw e; }
+  }
+  if (require('./lib/desktop').normalizeBrand(prep.browserBrand) !== 'chrome') {
+    try {
+      const context = await browser.newContext();
+      try { await require('./lib/desktop').requireEngine(context, prep.browserBrand); } finally { await context.close(); }
+    } catch (e) { await browser.close(); throw e; }
+  }
+  return browser;
+}
+
+async function requireMobileEngine(context, mobileDevice = null, seed = 0, platform = 'android') {
+  const page = await context.newPage();
+  try {
+    const mobile = require('./lib/mobile');
+    const expected = mobile.mobileProfile(seed, mobileDevice, platform);
+    await page.route('**/*', route => route.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html>' }));
+    await page.goto('https://capium-mobile-preview.invalid/', { waitUntil: 'domcontentloaded' });
+    const supported = await page.evaluate(mobile.engineProbe, expected);
+    if (!supported) throw new Error('This binary does not support the requested mobile profile/device; use Capium 1.2.1 revision 2 or later');
+  } finally { await page.close(); }
 }
 
 /**
@@ -207,17 +237,18 @@ async function launch(opts = {}) {
  */
 async function launchPersistentContext(userDataDir, opts = {}) {
   const {
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight,
     headless = false, ...rest
   } = opts;
   const prep = await prepare({
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight, headless,
   });
   // Default to the page filling the window (see launchContext) unless the caller pinned a
   // viewport themselves. viewport: null is Playwright-JS for "no fixed viewport".
-  if (!('viewport' in rest)) rest.viewport = null;
+  if (prep.mobileSeed !== null) Object.assign(rest, require('./lib/mobile').contextOptions(prep.mobileSeed, rest, prep.mobileDevice, prep.mobilePlatform));
+  else if (!('viewport' in rest)) rest.viewport = null;
   const pw = requireDriver();
   let ctx;
   try {
@@ -236,6 +267,11 @@ async function launchPersistentContext(userDataDir, opts = {}) {
   }
   clearStatusFile(prep.statusPath);
   ctx._capiumSeed = prep.finalSeed;
+  if (prep.mobileSeed !== null) {
+    try { await requireMobileEngine(ctx, prep.mobileDevice, prep.finalSeed, prep.mobilePlatform); } catch (e) { await ctx.close(); throw e; }
+  }
+  try { await require('./lib/desktop').requireEngine(ctx, prep.browserBrand); }
+  catch (e) { await ctx.close(); throw e; }
   return ctx;
 }
 
@@ -283,10 +319,10 @@ async function launchContext(opts = {}) {
   // viewport: null -- let the page fill the real window (fitWindow sizes the window to the
   // persona's screen). A fixed 1280x720 emulated viewport would leave the page smaller than
   // the window AND mismatch window.screen -- an incoherent fingerprint.
-  const context = browser.contexts()[0] || (await browser.newContext({ viewport: null }));
+  const context = browser.contexts()[0] || (await browser.newContext(browser._capiumMobile ? {} : { viewport: null }));
   if (humanize) human.humanize(context, humanPreset);
   const page = context.pages()[0] || (await context.newPage());
-  if (!headless) await fitWindow(browser, context, page); // modest window <= spoofed screen
+  if (!headless && !browser._capiumMobile) await fitWindow(browser, context, page); // modest window <= spoofed screen
   if (url) await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
   return { browser, context, page };
 }

package/puppeteer.js

@@ -76,24 +76,27 @@ async function resolveBinary(binary, licenseKey) {
 
 async function prepare(opts) {
   const {
-    seed = null, platform = 'windows', proxy = null, geoip = null, args = null,
+    seed = null, platform = 'windows', mobileDevice = null, browserBrand = null, proxy = null, geoip = null, args = null,
     stealthArgs = true, timezone = null, locale = null, extensionPaths = null,
     binary = null, licenseKey = null, licenseServer = null,
     licenseThroughProxy = false, licensePreflight = true, headless = false,
   } = opts;
+  require('./lib/desktop').validateLaunch(browserBrand, platform, binary, args, stealthArgs);
+  require('./lib/mobile').validateLaunch(platform, binary, args, stealthArgs, mobileDevice);
   if (licensePreflight) license.preflight(licenseKey, licenseServer);
   const { key } = license.effective(licenseKey, licenseServer);
   const binPath = await resolveBinary(binary, key);
   const finalSeed = seed === null || seed === undefined ? config.newSeed() : seed;
   const { launchOptions, args: proxyArgs } = proxyAndGeoArgs(proxy, geoip);
   const launchArgs = proxyArgs.concat(buildArgs({
-    seed: finalSeed, platform, stealthArgs, timezone, locale, extensionPaths, extra: args,
+    seed: finalSeed, platform, mobileDevice, browserBrand, stealthArgs, timezone, locale, extensionPaths, extra: args,
     headless,
   }));
   if (licenseThroughProxy) launchArgs.push('--license-through-proxy');
   const env = license.childEnv(licenseKey, licenseServer);
   const statusPath = newStatusFile(env);
-  return { binPath, finalSeed, launchOptions, launchArgs, env, statusPath };
+  return { binPath, finalSeed, launchOptions, launchArgs, env, statusPath,
+    browserBrand, mobileSeed: ['android', 'ios'].includes(platform) && stealthArgs ? finalSeed : null, mobileDevice, mobilePlatform: platform };
 }
 
 /**
@@ -131,12 +134,12 @@ async function throwTranslated(e, statusPath) {
  */
 async function buildLaunchOptions(opts = {}) {
   const {
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight,
     headless = false, ignoreDefaultArgs, ...rest
   } = opts;
   const prep = await prepare({
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight, headless,
   });
   const proxyOption = prep.launchOptions.proxy || null;
@@ -150,7 +153,8 @@ async function buildLaunchOptions(opts = {}) {
     headless,
     args: launchArgs,
     env: prep.env,
-    defaultViewport: 'defaultViewport' in rest ? rest.defaultViewport : null,
+    defaultViewport: 'defaultViewport' in rest ? rest.defaultViewport :
+      (prep.mobileSeed !== null ? require('./lib/mobile').puppeteerViewport(prep.mobileSeed, prep.mobileDevice, prep.mobilePlatform) : null),
     ignoreDefaultArgs: ignoreDefaultArgs === undefined ? config.IGNORE_DEFAULT_ARGS : ignoreDefaultArgs,
     ...rest,
   };
@@ -163,12 +167,12 @@ async function buildLaunchOptions(opts = {}) {
  */
 async function launch(opts = {}) {
   const {
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight,
     headless = false, ignoreDefaultArgs, ...rest
   } = opts;
   const prep = await prepare({
-    seed, platform, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
+    seed, platform, mobileDevice, browserBrand, proxy, geoip, args, stealthArgs, timezone, locale, extensionPaths,
     binary, licenseKey, licenseServer, licenseThroughProxy, licensePreflight, headless,
   });
   const puppeteer = requireDriver();
@@ -191,7 +195,8 @@ async function launch(opts = {}) {
       headless,
       args: launchArgs,
       env: prep.env,
-      defaultViewport: 'defaultViewport' in rest ? rest.defaultViewport : null,
+      defaultViewport: 'defaultViewport' in rest ? rest.defaultViewport :
+        (prep.mobileSeed !== null ? require('./lib/mobile').puppeteerViewport(prep.mobileSeed, prep.mobileDevice, prep.mobilePlatform) : null),
       ignoreDefaultArgs: ida,
       ...rest,
       // A rejected native gate never creates a page. Obtain the transport first,
@@ -215,6 +220,23 @@ async function launch(opts = {}) {
   clearStatusFile(prep.statusPath);
   wireProxyAuth(browser, proxyOption);
   browser._capiumSeed = prep.finalSeed;
+  browser._capiumMobile = prep.mobileSeed !== null;
+  if (browser._capiumMobile) {
+    try {
+      const page = await browser.newPage();
+      try {
+        const mobile = require('./lib/mobile');
+        const expected = mobile.mobileProfile(prep.finalSeed, prep.mobileDevice, prep.mobilePlatform);
+        await page.setRequestInterception(true);
+        page.on('request', request => request.respond({ status: 200, contentType: 'text/html', body: '<!doctype html>' }));
+        await page.goto('https://capium-mobile-preview.invalid/', { waitUntil: 'domcontentloaded' });
+        const supported = await page.evaluate(mobile.engineProbe, expected);
+        if (!supported) throw new Error('This binary does not support the requested mobile profile/device; use Capium 1.2.1 revision 2 or later');
+      } finally { await page.close(); }
+    } catch (e) { await browser.close(); throw e; }
+  }
+  try { await require('./lib/desktop').requirePuppeteerEngine(browser, prep.browserBrand); }
+  catch (e) { await browser.close(); throw e; }
   return browser;
 }
 
@@ -265,7 +287,7 @@ async function launchContext(opts = {}) {
   const pages = await browser.pages();
   const page = pages[0] || (await browser.newPage());
   if (humanize) human.humanize(page, humanPreset);
-  if (!headless) await fitWindow(browser, page);
+  if (!headless && !browser._capiumMobile) await fitWindow(browser, page);
   if (url) await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
   return { browser, page };
 }