capiumbrowser 1.2.0 → 1.2.2

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

@@ -1,32 +1,36 @@
 {
-  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline. `version` is the Chromium version (what the browser reports to the customer -- unchanged by the revision); `revision` is our packaging counter -- the served R2 folder is chromium-v<version>.<revision>/, ALWAYS dotted-suffixed starting at 1 (chromium-v<version>.1/ is the first build, .2/ a same-engine re-spin), so publishing a re-spin never overwrites the artifact older SDKs still fetch. `published: false` means the tag is declared but no artifact exists yet -- the SDK raises a clear 'not published yet' error instead of a raw 404.",
+  "_comment": "SINGLE SOURCE OF TRUTH for the current stable Capium browser build per OS/arch. Each OS reaches stable independently -- edit one entry without touching the others. This file ships inside the wheel (the SDK reads it to pick each host's stable build) AND is published to the download server by the release pipeline. `version` is the reported Chromium version (what the browser reports to the customer, names the R2 folder); `engine_version` is the actual built Chromium engine (box_package verifies the binary against it) -- it differs from `version` when a platform reports a spoofed patch (Windows reports .85 on the .84 engine). `revision` is our packaging counter -- the served R2 folder is chromium-v<version>.<revision>/, ALWAYS dotted-suffixed starting at 1. A Chromium version bump resets revision to 1. `published: false` means the tag is declared but no artifact exists yet.",
   "schema": 1,
-  "updated": "2026-10-10",
+  "updated": "2026-10-21",
   "channels": {
     "stable": {
       "windows-x64": {
-        "version": "155.0.8059.39",
+        "version": "155.0.8059.85",
+        "engine_version": "155.0.8059.84",
         "revision": 1,
-        "sha256": "d973e2460ce05e99f7e5c1dddc319ae96733434d9986dadc4cec5bac1c2597fb",
+        "sha256": "e10c944fc23637adb8d2f9206dbd69c595d51ba9de0cfd8140c9a2b5dc3510fc",
         "published": true,
         "license_status_protocol": 1
       },
       "macos-arm64": {
-        "version": "155.0.8059.39",
+        "version": "155.0.8059.84",
+        "engine_version": "155.0.8059.84",
         "revision": 1,
-        "sha256": "f07d54b88feb6644388196d6b91c9787592c1f6e07a8122344f47faed76b9262",
+        "sha256": "273bdd754b06538f633d2830f6fb8e3f02df226f093cb42acd052c0fece74127",
         "published": true,
         "license_status_protocol": 1
       },
       "linux-x64": {
-        "version": "155.0.8059.39",
+        "version": "155.0.8059.84",
+        "engine_version": "155.0.8059.84",
         "revision": 1,
-        "sha256": "a15cd395e1f8b792d9539c8284edcd589c6b91ef77f8b1fa5ea408f1f220b540",
+        "sha256": "e01b9b2179d82594e552f17aa0fad620785b4dfbf368c10c0ea146b5ce31c4e4",
         "published": true,
         "license_status_protocol": 1
       },
       "linux-arm64": {
-        "version": "155.0.8059.39",
+        "version": "155.0.8059.84",
+        "engine_version": "155.0.8059.84",
         "revision": 1,
         "sha256": null,
         "published": false

package/lib/config.js

@@ -24,12 +24,14 @@ const path = require('path');
 //                                 the deployed environment for either backend.
 const IGNORE_DEFAULT_ARGS = ['--enable-automation', '--enable-unsafe-swiftshader'];
 
-// The 155 engine selects a seeded screen within these default bounds. Start
-// headless windows small enough to fit its modes without replacing the screen.
-// Explicit screen/window flags take
-// precedence. HEADLESS_SCREEN remains the upper bound for existing consumers.
+// The 155 engine selects a seeded screen within these default bounds. The headless
+// window is sized PER SEED after launch (fitWindow -> the seed's screen.availWidth/Height),
+// giving a coherent maximized viewport < screen for every profile. HEADLESS_VIEWPORT is only
+// the brief STARTUP fallback before that fit runs; it must fit the smallest default seeded
+// screen (win/linux min is 1280x720), so it is NOT the 800x600 headless-Chrome default tell.
+// Explicit screen/window flags take precedence.
 const HEADLESS_SCREEN = [1920, 1080];
-const HEADLESS_VIEWPORT = [800, 600];
+const HEADLESS_VIEWPORT = [1280, 720];
 
 function getHeadlessDefaultArgs() {
   const [vw, vh] = HEADLESS_VIEWPORT;
@@ -48,13 +50,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 +130,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.2",
   "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,18 @@ 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; }
+  // Desktop personas: size the window to the seed's screen -- in HEADLESS too, so the
+  // viewport is a coherent per-seed maximized size instead of the tiny startup window.
+  // Mobile keeps its device viewport.
+  if (prep.mobileSeed === null) {
+    const page = ctx.pages()[0] || await ctx.newPage();
+    await fitWindow(ctx.browser(), ctx, page);
+  }
   return ctx;
 }
 
@@ -246,6 +289,7 @@ async function launchPersistentContext(userDataDir, opts = {}) {
  * window to <= the available screen with a slight offset. No-op on failure/headless.
  */
 async function fitWindow(browser, context, page) {
+  let pcdp, bcdp;
   try {
     const scr = await page.evaluate(() => ({ w: screen.availWidth, h: screen.availHeight }));
     if (!scr || !scr.w || !scr.h) return;
@@ -257,16 +301,21 @@ async function fitWindow(browser, context, page) {
     const h = ah;
     const left = 0;
     const top = 0;
-    const pcdp = await context.newCDPSession(page);
+    pcdp = await context.newCDPSession(page);
     const { targetInfo } = await pcdp.send('Target.getTargetInfo');
-    const bcdp = await browser.newBrowserCDPSession();
+    // Persistent contexts may have no Browser handle; their page session still
+    // supports the Browser window commands.
+    bcdp = browser ? await browser.newBrowserCDPSession() : pcdp;
     const { windowId } = await bcdp.send('Browser.getWindowForTarget',
       { targetId: targetInfo.targetId });
     await bcdp.send('Browser.setWindowBounds', {
       windowId,
       bounds: { left, top, width: w, height: h, windowState: 'normal' },
     });
-  } catch {}
+  } catch {} finally {
+    if (bcdp && bcdp !== pcdp) await bcdp.detach().catch(() => {});
+    if (pcdp) await pcdp.detach().catch(() => {});
+  }
 }
 
 /**
@@ -283,10 +332,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 (!browser._capiumMobile) await fitWindow(browser, context, page); // per-seed screen fit (headed + headless)
   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;
 }
 
@@ -224,11 +246,19 @@ async function launch(opts = {}) {
  * Returns the Browser.
  */
 async function launchPersistentContext(userDataDir, opts = {}) {
-  return launch({ ...opts, userDataDir });
+  const browser = await launch({ ...opts, userDataDir });
+  // Desktop personas: fit the window to the seed's screen in HEADLESS too (coherent per-seed
+  // viewport, not the tiny startup window). Mobile keeps its device viewport.
+  if (!browser._capiumMobile) {
+    const page = (await browser.pages())[0] || await browser.newPage();
+    await fitWindow(browser, page);
+  }
+  return browser;
 }
 
 /** Size a modest windowed browser that fits within the seed's spoofed screen. */
 async function fitWindow(browser, page) {
+  let cdp;
   try {
     const scr = await page.evaluate(() => ({ w: screen.availWidth, h: screen.availHeight }));
     if (!scr || !scr.w || !scr.h) return;
@@ -240,7 +270,7 @@ async function fitWindow(browser, page) {
     const h = ah;
     const left = 0;
     const top = 0;
-    const cdp = await page.createCDPSession();
+    cdp = await page.createCDPSession();
     const { targetInfo } = await cdp.send('Target.getTargetInfo');
     const { windowId } = await cdp.send('Browser.getWindowForTarget',
       { targetId: targetInfo.targetId });
@@ -248,8 +278,9 @@ async function fitWindow(browser, page) {
       windowId,
       bounds: { left, top, width: w, height: h, windowState: 'normal' },
     });
-    await cdp.detach();
-  } catch {}
+  } catch {} finally {
+    if (cdp) await cdp.detach().catch(() => {});
+  }
 }
 
 /**
@@ -265,7 +296,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 (!browser._capiumMobile) await fitWindow(browser, page); // per-seed screen fit (headed + headless)
   if (url) await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
   return { browser, page };
 }