capiumbrowser 1.1.8 → 1.2.1

package/README.md

@@ -35,10 +35,10 @@ Not a patched config. Not a JavaScript injection. A real Chromium binary whose f
 > Using Python? The same browser ships as a [PyPI package](https://pypi.org/project/capiumbrowser/) with the same options.
 
 - **Source-level C++ stealth** — User-Agent & UA-CH, WebGL/GPU, canvas, audio, screen, hardware, fonts, voices, WebRTC, `navigator.webdriver`, DevTools, pointer, client-rects — all rewritten **in the browser's own source**, below the JavaScript layer.
-- **Coherent per-seed identities** — one integer **seed** derives a complete, self-consistent device (OS, GPU, cores, memory, screen, fonts, UA). Same seed ⇒ same machine, on any host, every run.
+- **Repeatable per-seed identities** — one integer **seed** selects OS, GPU, cores, memory, screen, fonts and UA settings. Rendering still depends on the host; the same seed does not reproduce the same physical device across hosts.
 - **`humanize: true`** — attaches `page.humanMove` / `humanClick` / `humanType` / `humanScroll`: curved, human-timed mouse, keyboard, and scroll input.
 - **`geoip: true`** — the binary resolves its own exit IP through your proxy and pins timezone, WebRTC IP, geolocation, and `navigator.languages` to match. The clock, locale, and IP all tell one story.
-- **Plain drivers over CDP** — no patched driver, no init-script signature, no `Object.defineProperty` shim to detect. Update the engine with `npm i -U playwright-core` (or `puppeteer-core`).
+- **Plain drivers over CDP** — no patched driver or fingerprint `Object.defineProperty` shim. Update the driver with `npm i -U playwright-core` (or `puppeteer-core`); select the Capium browser binary separately.
 - **Always the latest binary** — one license key fetches the newest checksum-verified build for your platform and reuses it thereafter.
 - **Free tier — 1 concurrent session.** Paid tiers raise the concurrent-session cap. [Start free →](https://capiumbrowser.com)
 
@@ -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)
@@ -142,13 +143,14 @@ Puppeteer `Browser`:
 - **Config-level stealth breaks.** `puppeteer-extra-plugin-stealth`, patched drivers, and
   friends inject JavaScript or flip flags. Every Chrome update breaks them, and modern
   anti-bot ML detects the patches themselves — the very act of hiding trips the alarm.
-- **Capium patches Chromium source.** Fingerprints are modified at the C++ level and compiled
-  into the binary. Detection sites see a real browser because it *is* one — no init script,
-  no `toString` tampering, no CDP hooks to sniff.
-- **Coherence is the product.** A convincing device isn't one clean signal; it's *every*
-  signal telling the same story. Capium derives GPU, screen, fonts, UA-CH, timezone, locale,
-  and WebRTC from a single seed + your proxy's geography, so nothing contradicts anything else.
-- **Same behavior everywhere.** Local, Docker, VPS, Lambda — no environment-specific config.
+- **Capium patches Chromium source.** Fingerprint changes are compiled into the browser at the C++
+  level. SDK evaluation and exposed bindings can still reveal driver behavior; see the measured
+  [Chrome 155 audit](../../docs/SDK-GPU-AUDIT.md).
+- **Coherence needs measurement.** A seed selects identity settings, and optional proxy geography
+  aligns network-related settings. Native rendering, fonts and server classifications still depend
+  on the host and launch policy; matching the persona to the host performs better in the current audit.
+- **Common launch API.** Local, Docker, VPS and Lambda deployments need their own display, graphics
+  dependency and proxy checks.
 - **Works with your stack.** Drop-in stealth for Crawlee, @playwright/test,
   puppeteer-cluster, and anything that speaks CDP. See [integrations](#framework-integrations).
 
@@ -184,11 +186,11 @@ See **[capiumbrowser.com/#pricing](https://capiumbrowser.com/#pricing)** for cur
 ### Get a key
 
 1. Create an account at **[capiumbrowser.com](https://capiumbrowser.com)** and create a license (start with the
-   free 1-session tier). Keys look like `cap_XXXXXXXXXXXXXXXXXXXXXXXX`.
+   free 1-session tier). Keys look like `cap_your_license_key`.
 2. Make it available to the SDK any one way (checked in this order):
 
    ```bash
-   export CAPIUM_LICENSE_KEY="cap_xxxxxxxxxxxxxxxxxxxx"
+   export CAPIUM_LICENSE_KEY="cap_your_license_key"
    # optional — defaults to https://license.capzy.ai
    export CAPIUM_LICENSE_SERVER="https://license.capzy.ai"
    ```
@@ -213,8 +215,17 @@ Handle license errors with typed error classes — `CapiumSeatLimitError`, `Capi
 
 ## What a persona reads
 
-On a **matching-OS host** (a Windows persona on Windows, a macOS persona on macOS), a Capium persona reads
-clean against a modern fingerprinting suite — with the correct GPU, fonts, and voices for the claimed device:
+The table below retains historical Chrome 152 observations. These are examples,
+not guarantees for every seed, SDK driver, host or detector revision.
+The [Chrome 155 SDK/proxy audit](../../docs/reports/sdk-public-audit-155-2026-10-09.html)
+records current BrowserScan and Fingerprint observations through Node Playwright/
+Puppeteer and Python sync/async on all three hosts. Matched Windows/Mac personas
+have clean tampering observations; Linux and cross-OS cases remain flagged.
+Local API checks do not establish a public verdict or certify a seeded GPU as
+physical hardware.
+The active Rebrowser checks also detect driver stack labels, main-world DOM calls
+and exposed bindings. A clean launch observation does not cover every script's
+behavior or make `page.evaluate()` / `exposeFunction()` invisible to the page.
 
 | Signal | Stock driver Chromium | Capium |
 |---|---|---|
@@ -228,11 +239,13 @@ clean against a modern fingerprinting suite — with the correct GPU, fonts, and
 | JA4 TLS fingerprint | differs from Chrome | **matches stock Chrome** |
 | WebRTC IP behind a proxy | real IP leaks | **pinned to the proxy exit** |
 
-> **Honesty matters more than a green screenshot.** A **GPU-less headless Linux** box makes WebGL fall back
-> to SwiftShader, which any modern suite (and stock Chrome) flags as `virtual_machine` / `anti_detect` — an
-> artifact of the *host*, not the browser. Run **headed** (Xvfb is fine) on a GPU-backed, matching-OS host
-> for the clean verdict. And `os_mismatch` is a **network** signal — genuine Chrome trips it behind some
-> proxies/NATs too, so treat it as a routing concern, not a browser one.
+> Software rendering can initialize WebGL without reproducing a hardware GPU.
+> A seeded renderer name does not change the actual device or establish a clean
+> detector verdict. On the tested 155 Linux/Xvfb stack, defaults provide headless
+> WebGL but headed contexts are absent; explicit Mesa flags initialize both modes.
+> Use matched stock/native controls and verify the assigned browser proxy exit
+> before and after each public target. Keep unavailable contexts and unmeasured
+> server verdicts explicit.
 
 ---
 
@@ -328,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)). |
@@ -430,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 —
@@ -652,16 +704,20 @@ launches **headed**, which reads cleaner than headless.
 
 | Platform | Distro tag | Notes |
 |---|---|---|
-| Windows x86_64 | `windows-x64` | Native GPU/fonts back a Windows persona flawlessly |
-| macOS arm64 (Apple Silicon) | `macos-arm64` | M1–M4 by design (covers 2020+ Macs); a Windows persona uses installed Windows fonts for fallback |
-| Linux x86_64 | `linux-x64` | Defaults to a Windows persona; supply Windows fonts for the cleanest result |
-| Linux arm64 | `linux-arm64` | Same as Linux x64 for aarch64 hosts |
+| Windows x86_64 | `windows-x64` | Native Windows GPU/fonts support a matching persona; seeded hardware fidelity still requires measurement |
+| macOS arm64 (Apple Silicon) | `macos-arm64` | Native Apple graphics support a matching persona; cross-OS identities need separate checks |
+| Linux x86_64 | `linux-x64` | Defaults to a Windows persona; select a matching Linux persona and verify the deployment's graphics stack |
+| 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. Capium currently targets **Chromium 152**.
+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 launch APIs wait for the packaged browser's licensing decision before
+returning a handle. Invalid keys raise a typed error during launch.
+
 ## CLI & environment
 
 ```bash
@@ -695,12 +751,13 @@ license key; it prints a fix for anything missing and exits non-zero if the envi
 | `no license configured` | Set `CAPIUM_LICENSE_KEY`, pass `licenseKey: '…'`, or create `~/.capium/license` (`KEY=cap_…`). |
 | `playwright-core is not installed` | `npm install playwright-core` (or `puppeteer-core`) — the driver is a peer dependency you choose. |
 | `CapiumSeatLimitError` | Free tier is 1 concurrent session — close the other Capium browser (or upgrade the tier). |
-| Still blocked on aggressive sites | Run **headed** (`headless: false` under Xvfb) + a **residential** proxy + `geoip: true` + humanized input. Most blocks are IP reputation or a mismatched clock, not fingerprint. |
+| Still blocked on aggressive sites | Compare a matching persona with stock Chrome through assigned proxies. Check route, timezone, graphics availability and detector fields separately; headed mode under Xvfb also needs a working graphics backend. |
 | Intermittent 403s on reCAPTCHA Enterprise sites | Prefer the **Playwright** front-end — Puppeteer's CDP protocol usage leaks more automation signals (a Puppeteer limitation, not a Capium one). |
-| FPJS `tampering: true` | Cross-OS persona on a mismatched host, or per-seed noise unmasked — run on a matching-OS host; `--fingerprint-noise=false` is the default. |
+| FPJS `tampering: true` | Prefer a matching-OS host and keep the default `--fingerprint-noise=false`. The current Linux audit remains flagged even with hardware Vulkan; ML zero alone does not clear tampering or anomaly. See the [audit](../../docs/SDK-GPU-AUDIT.md). |
 | "Windows persona but missing fonts" | Supply real `C:\Windows\Fonts\*.ttf` (see [Fonts](#fonts)) or set `CAPIUM_SUPPRESS_FONT_WARNING=1`. |
 | `os_mismatch: true` | A network/transport signal (genuine Chrome shows it too behind some proxies) — a routing concern, not the browser. |
 | Headed browser won't start on a server | Run under `Xvfb` and export `DISPLAY=:99`. |
+| Chrome 155 dev: intermittent headed Puppeteer startup on macOS | The owned-origin matrix reproduced launch timeouts with both WebSocket and pipe transport. An active process sample waited in the licensing startup gate before page probes; the exact cause remains unresolved. Python and Node Playwright headed launches, and Puppeteer headless launches, completed in the matrix. |
 
 More: [docs.capiumbrowser.com](https://docs.capiumbrowser.com).
 

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,33 @@
 {
   "_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.",
   "schema": 1,
-  "updated": "2026-10-08",
+  "updated": "2026-10-10",
   "channels": {
     "stable": {
       "windows-x64": {
-        "version": "153.0.8010.53",
-        "engine_version": "153.0.8010.52",
-        "revision": 5,
-        "sha256": "3f53b86f80a3b145cb75995615f19c957a74d6a1a0ae1151ff64517b3a931d67",
-        "published": true
+        "version": "155.0.8059.39",
+        "revision": 2,
+        "sha256": "25ef98b8713c2c9fb62615b4c9aa0d7a3bd20c76320ec3d99e848775b1d4fdd6",
+        "published": true,
+        "license_status_protocol": 1
       },
       "macos-arm64": {
-        "version": "153.0.8010.53",
-        "engine_version": "153.0.8010.52",
-        "revision": 6,
-        "sha256": "eca400433d74e5ac3b59fa1764bba783674a05cfc5a34598c8c1d2f02c708e18",
-        "published": true
+        "version": "155.0.8059.39",
+        "revision": 2,
+        "sha256": "2c39538576a8c5f63b39ac1f09cdb1cc5f7d2b6899ed7625752c6c4c2737a90f",
+        "published": true,
+        "license_status_protocol": 1
       },
       "linux-x64": {
-        "version": "153.0.8010.52",
-        "revision": 5,
-        "sha256": "f65f11a2b15dea523ee95e35cadbbd43c77aba4751cdc0f96f8c138143f041bb",
-        "published": true
+        "version": "155.0.8059.39",
+        "revision": 2,
+        "sha256": "87889050d6a1e46a8aabe4800f8fff5e474a07cd23e22a66f79b830f5544487c",
+        "published": true,
+        "license_status_protocol": 1
       },
       "linux-arm64": {
-        "version": "153.0.8010.52",
-        "revision": 1,
+        "version": "155.0.8059.39",
+        "revision": 2,
         "sha256": null,
         "published": false
       }

package/lib/config.js

@@ -2,14 +2,11 @@
  * config -- default stealth arguments and binary discovery.
  *
  * The capium binary is driven through its `capium` bash wrapper (executablePath), which
- * adds the GL/Metal backend, geoip, font, bluetooth/share and storage-quota flags per platform.
+ * supports explicit backend selection and platform flags; geoip remains opt-in.
  * This module only builds the *fingerprint-level* Chrome flags and locates that wrapper.
  *
- * Design note (why no stealth plugin): capium's own source patches make a vanilla driver
- * stealthy --
- *   001 (disable Runtime.enable console-reporting)  -> FingerprintJS developer_tools = false
- *   009 (webdriver)                                 -> navigator.webdriver = false
- * so we launch with plain Playwright / Puppeteer and let the binary do the CDP hardening.
+ * The binary handles CDP isolation and console masking, plus the webdriver surface.
+ * We launch with plain drivers; detector outcomes still require native host tests.
  */
 'use strict';
 
@@ -20,29 +17,23 @@ const path = require('path');
 // Playwright/Puppeteer default args to SUPPRESS (ignoreDefaultArgs): these leak automation
 // or force a software render.
 //   --enable-automation         : exposes navigator.webdriver=true + an automation banner.
-//   --enable-unsafe-swiftshader : the driver adds this so headless WebGL "works", but it ENABLES
-//                                 the (for us, broken-ICD) bundled SwiftShader path -> getContext
-//                                 ('webgl')=null headless / a software-raster tell. Stripping it
-//                                 forces Chromium onto the real GPU (GPU host) or system Mesa.
+//   --enable-unsafe-swiftshader : permits a software fallback. Keep that choice
+//                                 explicit instead of inheriting a driver's default.
+//                                 The historical 153 package lacked its ICD manifest;
+//                                 the 155 packager includes it. Validate drawing in
+//                                 the deployed environment for either backend.
 const IGNORE_DEFAULT_ARGS = ['--enable-automation', '--enable-unsafe-swiftshader'];
 
-// Headless default screen/viewport. Headless has no real display, so the per-seed device-pool
-// screen (e.g. 2560x1440) has no window manager to size a matching window against -- the
-// framebuffer would stay at Chromium's small headless default and screen != viewport (a
-// browserscan VM tell). Instead model the single MOST COMMON real setup: a maximized Chrome
-// window on a 1080p Windows monitor -- screen 1920x1080, viewport 1920x947 (1040 avail height
-// minus ~93px of tab/omnibox/bookmark chrome). Dominant real-world viewport, so a headless
-// instance blends in, and screen > viewport stays coherent. Applied only in headless and only
-// when the caller pins no screen (an explicit --fingerprint-screen-* / --window-size opts out).
+// 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.
 const HEADLESS_SCREEN = [1920, 1080];
-const HEADLESS_VIEWPORT = [1920, 947];
+const HEADLESS_VIEWPORT = [800, 600];
 
 function getHeadlessDefaultArgs() {
-  const [sw, sh] = HEADLESS_SCREEN;
   const [vw, vh] = HEADLESS_VIEWPORT;
   return [
-    `--fingerprint-screen-width=${sw}`,
-    `--fingerprint-screen-height=${sh}`,
     `--window-size=${vw},${vh}`,
   ];
 }
@@ -57,15 +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.
- * screen:   DEFAULT null -> use the seed's COHERENT per-seed device screen from the binary's
- *           device pool (GPU-matched resolution + realistic dpr); fitWindow then sizes the window
- *           to it so viewport ~= screen. Passing an explicit [w,h] FORCES that resolution on every
- *           seed (all instances share one screen AND can pair e.g. an RTX 5080 with 1440x900) --
- *           only for a fixed-kiosk scenario. (Previously defaulted to [1440,900], a cross-instance
- *           correlation + GPU-incoherence tell -- now matches the python SDK's screen=None.)
+ * 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));
@@ -91,17 +102,15 @@ function getDefaultStealthArgs(seed = null, platform = 'windows', screen = null)
       'primaryPointerType=4,availablePointerTypes=4',
     '--no-first-run',
     '--no-default-browser-check',
-    // NOTE: capium "CDP stealth" (isolated-world eval + console-API masking that make a vanilla
-    // driver behave like patchright vs DataDome/rebrowser) is ON BY DEFAULT in the binary -- no
-    // flag needed. To opt out (e.g. a solver needing page.evaluate to read the page's own
-    // main-world window globals, which the isolated world can't see), pass
-    // extra: ['--capium-disable-cdp-stealth'].
+    // Engine 155 honors the requested execution world by default. Its console
+    // event policy is independent of page evaluation. Engine 153 retains the
+    // older default isolation behavior; --capium-isolate-cdp-eval explicitly
+    // requests that legacy mode on 155. See docs/SDK-GPU-AUDIT.md for measured
+    // page-global, object-handle and binding compatibility.
   );
-  // Patch 001 makes developer_tools always false, which unmasks FingerprintJS's
-  // tampering ML: per-seed canvas/audio NOISE would then read as tampering, so
-  // default it OFF (measured clean: tampering=false, ml~0.05, anti_detect=false).
-  // Trade-off: personas on the same host share its real canvas (no per-seed canvas
-  // uniqueness) -- pass --fingerprint-noise=true to restore it (accepts tampering).
+  // Keep injected canvas/audio/rectangle noise opt-in. Device fonts and the
+  // actual renderer can still affect pixels; noise=false does not guarantee
+  // identical canvases across personas or a particular detector classification.
   args.push('--fingerprint-noise=false');
   // A Windows persona's font metrics must match real Windows (needs Windows fonts
   // present on the host); harmless elsewhere, so gate it to the windows persona.
@@ -110,8 +119,8 @@ function getDefaultStealthArgs(seed = null, platform = 'windows', screen = null)
   // screen (e.g. 2560x1080) mismatches the actual small browser viewport (e.g.
   // 945x939) -- browserscan flags "screen dimensions don't match viewport" as a
   // virtual machine. Pin the spoofed screen to a window we also size, so
-  // screen == window == viewport in every environment (headless/container too),
-  // since the --window-size flag applies at launch without a window manager.
+  // --window-size requests the outer window; the inner viewport excludes Chrome's
+  // frame/UI and must be measured rather than assumed equal to screen dimensions.
   if (screen) {
     const sw = Math.trunc(Number(screen[0]));
     const sh = Math.trunc(Number(screen[1]));
@@ -119,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/errors.js

@@ -96,6 +96,7 @@ function readLaunchStatus(statusPath) {
   if (!raw.trim()) return null;
   const nl = raw.indexOf('\n');
   const code = (nl === -1 ? raw : raw.slice(0, nl)).trim();
+  if (code === '0') return null;
   const msg = (nl === -1 ? '' : raw.slice(nl + 1)).trim() ||
     'the browser refused to start for a licensing reason';
   const Cls = STATUS_CODES[code] || CapiumLicenseError;

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));
-    // Headless: pin the maximized-1080p-Windows screen/viewport (see config), unless the
-    // caller already set their own screen/window via extra args.
-    if (headless && !config.hasScreenOverride(extra)) {
+    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 && !['android', 'ios'].includes(platform) && !config.hasScreenOverride(extra)) {
       args = args.concat(config.getHeadlessDefaultArgs());
     }
   }

package/lib/license-readiness.js

@@ -0,0 +1,58 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { readLaunchStatus, CapiumServerDownError } = require('./errors');
+
+function required(binary) {
+  let directory = path.dirname(path.resolve(binary));
+  for (let i = 0; i < 8; i++) {
+    try {
+      const info = fs.readFileSync(path.join(directory, 'CAPIUM_BUILD_INFO'), 'utf8');
+      return /^license_status_protocol\s*:\s*1\s*$/m.test(info);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return false;
+}
+
+async function wait(binary, statusPath, timeoutMs = 30000, signal = null) {
+  if (!required(binary)) return;
+  const deadline = Date.now() + (timeoutMs || 30000);
+  for (;;) {
+    if (signal?.aborted) return;
+    const error = readLaunchStatus(statusPath);
+    if (error) throw error;
+    try {
+      if (fs.readFileSync(statusPath, 'utf8').trim() === '0\nCAPIUM_LICENSE_READY') return;
+    } catch (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');
+    }
+    await new Promise(resolve => setTimeout(resolve, 20));
+  }
+}
+// Drivers may leave startup pending after the native process refuses the license.
+// Observe the native decision while the driver connects, so rejection cannot hang.
+async function withLaunch(pending, binary, statusPath, timeoutMs) {
+  const controller = new AbortController();
+  try {
+    const [handle] = await Promise.all([
+      pending, wait(binary, statusPath, timeoutMs, controller.signal),
+    ]);
+    return handle;
+  } finally {
+    // A driver can reject before the native decision is written. Do not keep
+    // polling a removed status file, or keep Node alive until the deadline.
+    controller.abort();
+  }
+}
+module.exports = { required, wait, withLaunch };

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/lib/version.js

@@ -25,12 +25,12 @@ const SDK_VERSION = require('../package.json').version;
 // Used only if channels.json can't be read (corrupt/removed install). ensureBinary() raises a
 // clear error long before the "unsupported platform" case matters; this keeps lookups total.
 const FALLBACK_VERSIONS = {
-  'windows-x64': '153.0.8010.52', // real Chrome 152 stable per OS (win/mac .65, linux .64)
-  'macos-arm64': '153.0.8010.52',
-  'linux-x64': '153.0.8010.52',
-  'linux-arm64': '153.0.8010.52', // declared; not yet published (see channels.json)
+  'windows-x64': '155.0.8059.39', // Chromium 155 release candidate on all supported hosts
+  'macos-arm64': '155.0.8059.39',
+  'linux-x64': '155.0.8059.39',
+  'linux-arm64': '155.0.8059.39', // declared; not yet published (see channels.json)
 };
-const DEFAULT_BINARY_VERSION = '153.0.8010.52';
+const DEFAULT_BINARY_VERSION = '155.0.8059.39';
 
 function loadStable() {
   // The `channels.stable` map from the bundled manifest, or null if unreadable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capiumbrowser",
-  "version": "1.1.8",
+  "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

@@ -25,6 +25,7 @@ const config = require('./lib/config');
 const download = require('./lib/download');
 const human = require('./lib/human');
 const license = require('./lib/license');
+const readiness = require('./lib/license-readiness');
 const { CapiumError, translateLaunchError, readLaunchStatus } = require('./lib/errors');
 const { proxyAndGeoArgs, buildArgs, newStatusFile, clearStatusFile } =
   require('./lib/launch-common');
@@ -75,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) {
@@ -116,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 {
@@ -139,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);
     };
   }
@@ -170,28 +175,59 @@ 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();
   let browser;
   try {
-    browser = await pw.chromium.launch({
+    const pending = pw.chromium.launch({
       executablePath: prep.binPath, headless, args: prep.launchArgs, env: prep.env,
       ignoreDefaultArgs: config.IGNORE_DEFAULT_ARGS,   // strip automation + forced-software WebGL defaults
       ...prep.launchOptions, ...rest,
-    });
+    }).then(handle => { browser = handle; return handle; });
+    await readiness.withLaunch(pending, prep.binPath, prep.statusPath, rest.timeout);
   } catch (e) {
+    // A native refusal terminates the process; closing its dead CDP connection can hang.
+    if (!readLaunchStatus(prep.statusPath) && browser) {
+      try { await browser.close(); } catch {}
+    }
     await throwTranslated(e, prep.statusPath);
   }
   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(); }
 }
 
 /**
@@ -201,30 +237,41 @@ 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 {
-    ctx = await pw.chromium.launchPersistentContext(userDataDir, {
+    const pending = pw.chromium.launchPersistentContext(userDataDir, {
       executablePath: prep.binPath, headless, args: prep.launchArgs, env: prep.env,
       ignoreDefaultArgs: config.IGNORE_DEFAULT_ARGS,   // strip automation + forced-software WebGL defaults
       ...prep.launchOptions, ...rest,
-    });
+    }).then(handle => { ctx = handle; return handle; });
+    await readiness.withLaunch(pending, prep.binPath, prep.statusPath, rest.timeout);
   } catch (e) {
+    // A native refusal terminates the process; closing its dead CDP connection can hang.
+    if (!readLaunchStatus(prep.statusPath) && ctx) {
+      try { await ctx.close(); } catch {}
+    }
     await throwTranslated(e, prep.statusPath);
   }
   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;
 }
 
@@ -272,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

@@ -29,6 +29,7 @@ const config = require('./lib/config');
 const download = require('./lib/download');
 const human = require('./lib/human');
 const license = require('./lib/license');
+const readiness = require('./lib/license-readiness');
 const { CapiumError, translateLaunchError, readLaunchStatus } = require('./lib/errors');
 const { proxyAndGeoArgs, buildArgs, newStatusFile, clearStatusFile } =
   require('./lib/launch-common');
@@ -75,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 };
 }
 
 /**
@@ -130,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;
@@ -149,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,
   };
@@ -162,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();
@@ -181,23 +186,57 @@ async function launch(opts = {}) {
   }
   // Strip automation + forced-software WebGL defaults unless the caller took over ignoreDefaultArgs.
   const ida = ignoreDefaultArgs === undefined ? config.IGNORE_DEFAULT_ARGS : ignoreDefaultArgs;
+  const nativeGate = readiness.required(prep.binPath);
+  const waitForInitialPage = rest.waitForInitialPage !== false;
   let browser;
   try {
-    browser = await puppeteer.launch({
+    const pending = puppeteer.launch({
       executablePath: prep.binPath,
       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,
+      // so Puppeteer does not leave its initial-page timer running after refusal.
+      waitForInitialPage: nativeGate ? false : waitForInitialPage,
+    }).then(handle => { browser = handle; return handle; });
+    await readiness.withLaunch(pending, prep.binPath, prep.statusPath, rest.timeout);
+    if (nativeGate && waitForInitialPage) {
+      await browser.waitForTarget(target => target.type() === 'page', {
+        timeout: rest.timeout === undefined ? 30000 : rest.timeout,
+        signal: rest.signal,
+      });
+    }
   } catch (e) {
+    // A native refusal terminates the process; closing its dead CDP connection can hang.
+    if (!readLaunchStatus(prep.statusPath) && browser) {
+      try { await browser.close(); } catch {}
+    }
     await throwTranslated(e, prep.statusPath);
   }
   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;
 }
 
@@ -248,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 };
 }