capiumbrowser 0.1.0

package/LICENSE

@@ -0,0 +1,38 @@
+Capzy capiumbrowser SDK License
+
+Copyright (c) Capzy. All rights reserved.
+
+1. Definitions.
+   "SDK" means this Python package ("capiumbrowser"), its source, and its
+   documentation. "Browser Binary" means the Capium stealth Chromium build that
+   the SDK downloads and launches. "License Key" means a key issued by Capzy that
+   entitles you to run the Browser Binary.
+
+2. The SDK.
+   Capzy grants you a non-exclusive, non-transferable, royalty-free license to
+   install and use the SDK to launch the Browser Binary, and to modify the SDK for
+   your own internal use. You may not remove or alter this notice.
+
+3. The Browser Binary is licensed separately.
+   Use of the Browser Binary requires a valid License Key and is governed by the
+   Capzy Terms of Service. The Browser Binary is enforced per concurrent session;
+   see the documentation. Nothing in this SDK license grants any right to use the
+   Browser Binary without a valid License Key.
+
+4. Restrictions.
+   You may not sublicense, resell, or redistribute the Browser Binary. You may not
+   use the SDK or the Browser Binary to violate any applicable law or the rights of
+   any third party. You are responsible for using the software only where you are
+   authorized to do so.
+
+5. No warranty.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+   FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. Limitation of liability.
+   IN NO EVENT SHALL CAPZY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, visit https://capzy.ai.

package/README.md

@@ -0,0 +1,174 @@
+<h3 align="center">Capium — a stealth Chromium built to withstand bot detection, for Node.js.</h3>
+
+<p align="center">
+  <a href="https://capiumbrowser.com">capiumbrowser.com</a> ·
+  <a href="https://docs.capiumbrowser.com">Documentation</a> ·
+  <a href="https://capiumbrowser.com/#pricing">Pricing</a> ·
+  <a href="https://github.com/capzy-ai/capiumbrowser">Product overview</a> ·
+  <a href="https://pypi.org/project/capiumbrowser/">Python SDK</a>
+</p>
+
+---
+
+Not a patched config. Not a JavaScript injection. A real Chromium binary whose fingerprints are
+rewritten at the **C++ source level** and compiled in. Page scripts that hunt for injected hooks
+find nothing to catch — the values a site reads *are* the persona's values, produced by the
+engine. Drive it with the **Playwright** or **Puppeteer** API you already know.
+
+## Install
+
+```bash
+# With Playwright
+npm install capiumbrowser playwright-core
+
+# With Puppeteer
+npm install capiumbrowser puppeteer-core
+```
+
+The driver is a normal peer dependency, so you update the engine independently
+(`npm install -U playwright-core`). You do **not** run `npx playwright install chromium` —
+Capium ships its own binary. On first launch the SDK fetches the per-platform build from the
+license service (authenticated, checksum-verified) and caches it under `~/.capium`
+(`CAPIUM_HOME` overrides).
+
+## Quick start
+
+```js
+// Auto-detects the installed driver (Playwright preferred when both are present):
+const { launchContext } = require('capiumbrowser');
+
+// ...or pick one explicitly:
+// const { launchContext } = require('capiumbrowser/playwright');
+// const { launchContext } = require('capiumbrowser/puppeteer');
+
+const { browser, page } = await launchContext({
+  seed: 200123,                              // a coherent, repeatable device
+  platform: 'windows',                       // the spoofed OS persona
+  proxy: 'http://user:pass@host:port',
+  geoip: true,                               // exit IP + matching tz/geo/WebRTC
+  humanize: true,                            // human-like clicks/typing/scrolls
+  url: 'https://fingerprint.com/demo/',
+});
+
+await page.humanType('#email', 'alex@example.com');
+await page.humanClick('#submit');
+await browser.close();
+```
+
+The returned objects are standard Playwright / Puppeteer objects — the rest of your code is
+unchanged.
+
+```js
+// Playwright:  launch() -> Browser,  launchPersistentContext(dir) -> BrowserContext
+const { launch, launchPersistentContext } = require('capiumbrowser/playwright');
+const browser = await launch({ seed: 42 });
+const page = await (await browser.newContext({ viewport: null })).newPage();
+
+// Puppeteer:   launch() -> Browser (persistent profile via userDataDir)
+const pptr = require('capiumbrowser/puppeteer');
+const browser2 = await pptr.launch({ seed: 42, userDataDir: './profile' });
+```
+
+## Highlights
+
+- **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, every run.
+- **`humanize: true`** — attaches `page.humanMove/humanClick/humanType/humanScroll`: curved,
+  human-timed mouse, keyboard, and scroll.
+- **`geoip: true`** — the binary resolves its own exit IP through your proxy and pins timezone,
+  WebRTC IP, geolocation, and `navigator.languages` to match.
+- **Plain drivers over CDP** — no patched driver, no init-script signature, no
+  `Object.defineProperty` shim to detect.
+- **Always the latest binary** — one license key fetches the newest checksum-verified build for
+  your platform and reuses it thereafter.
+
+## Options (both drivers)
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `seed` | random | Identity seed; a stable, coherent device per seed |
+| `platform` | `"windows"` | Spoofed OS persona: `windows` \| `macos` \| `linux` |
+| `headless` | `false` | Windowed is the coherent persona default |
+| `proxy` | none | `"http://user:pass@host:port"`, `"socks5://host:port"`, or `{server, username, password, bypass}` |
+| `geoip` | off | `true` = pin tz/geo/WebRTC/language to the egress; `false` = explicit opt-out |
+| `timezone` / `locale` | — | Explicit overrides (IANA tz, BCP-47 locale; in-binary spoof) |
+| `stealthArgs` | `true` | `false` drops the default fingerprint flags |
+| `licenseKey` / `licenseServer` | env / `~/.capium/license` | Handed to the self-licensing binary via the environment, never argv |
+
+Remaining options are forwarded to the driver's own `launch()`.
+
+### Framework integrations
+
+`buildLaunchOptions()` (on both subpaths) returns the ready-made options object for the
+driver's own `launch()`, for frameworks that must hold the launch themselves (Crawlee,
+custom pools):
+
+```js
+const { chromium } = require('playwright-core');
+const { buildLaunchOptions } = require('capiumbrowser/playwright');
+const browser = await chromium.launch(await buildLaunchOptions({ seed: 42 }));
+```
+
+## License & binary
+
+The `capiumbrowser` npm package is open; the **Capium browser binary is licensed** per
+concurrent session (free tier: 1 concurrent session). Configure the key once:
+
+```bash
+export CAPIUM_LICENSE_KEY=cap_...        # or ~/.capium/license with a KEY= line
+```
+
+Enforcement lives **in the browser binary** (activate → session → heartbeat); the SDK only
+passes the key along and translates the binary's fail-closed exit into typed errors:
+`CapiumConfigError` (no key), `CapiumSeatLimitError`, `CapiumExpiredError`,
+`CapiumServerDownError`.
+
+## CLI
+
+```bash
+npx capiumbrowser            # environment check: license + binary + drivers
+npx capiumbrowser status     # license entitlements from the server
+npx capiumbrowser install    # download the capium browser binary
+npx capiumbrowser run [URL]  # demo launch (SEED/PLATFORM/PROXY/HEADLESS=1/PROFILE env)
+```
+
+## Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `CAPIUM_LICENSE_KEY` / `CAPIUM_LICENSE_SERVER` | License credentials (or `~/.capium/license`) |
+| `CAPIUM_HOME` | Install/search root for the browser binary (default `~/.capium`) |
+| `CAPIUM_BINARY` | Exact launch target; skips discovery and download |
+| `CAPIUM_VERSION` | Pin a specific binary build |
+| `CAPIUM_DOWNLOAD_URL` | Direct `.tar.gz` URL escape hatch (may contain `{platform}`/`{version}`) |
+| `CAPIUM_INLINE_PROXY_AUTH=0` | Legacy CDP proxy-auth path for old binaries |
+
+## Fonts (cross-OS personas)
+
+A persona reads cleanest on a **matching-OS host** (Windows persona on Windows, …) — the OS
+fonts back the claim and there's nothing to install. For a **Windows persona on Linux/macOS**,
+copy the fonts from a real Windows machine you own:
+
+```bash
+# Linux: copy C:\Windows\Fonts\* into a font dir, then refresh
+mkdir -p ~/.local/share/fonts/windows
+scp C:\Windows\Fonts\* user@linuxbox:~/.local/share/fonts/windows/   # from the Windows box
+fc-cache -f
+# macOS: drop the .ttf/.ttc files into ~/Library/Fonts/ (picked up immediately)
+```
+
+Once Segoe UI/Calibri/Consolas & co. resolve, the wrapper auto-enables
+`--fingerprint-windows-font-metrics`. `CAPIUM_FONTS_DIR=/path` points at a custom dir. Copy
+proprietary fonts only between machines you hold licenses for. Full guide: the
+[product README](https://github.com/capzy-ai/capiumbrowser#fonts).
+
+## Platforms
+
+`linux-x64` · `linux-arm64` · `windows-x64` · `macos-arm64` (Apple Silicon).
+
+> **Responsible use.** Capium is a stealth browser for legitimate automation, testing, QA, and
+> research. Capium doesn't solve CAPTCHAs, and no stealth tool can promise you'll never see
+> one. Respect the terms of service of the sites you automate.

package/bin/capiumbrowser.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * capiumbrowser CLI -- npx capiumbrowser <command>
+ *
+ *   info                environment check: license + binary + drivers (i.e. "what do I
+ *                       still need installed?"). Exit 0 if ready, 1 if not.
+ *   status              license entitlements from the server (plan, seats, live sessions)
+ *   version             SDK version + the Chromium/Capium build it targets
+ *   install             download the capium browser binary
+ *   run [URL]           launch a stealth browser to URL (demo; Ctrl-C to exit)
+ *
+ *   info/status flags:  --json   --quick (skip the license-server call)
+ *   run env:            SEED, PLATFORM (windows|macos|linux), HEADLESS=1, PROXY, GEOIP=1,
+ *                       PROFILE=<dir> (persistent), HUMANIZE=1
+ */
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+
+const config = require('../lib/config');
+const download = require('../lib/download');
+const license = require('../lib/license');
+const { CapiumError } = require('../lib/errors');
+const { SDK_VERSION, CAPIUM_BINARY_VERSION } = require('../lib/version');
+
+// ---- diagnostics helpers -----------------------------------------------------
+
+function driverVersion(name) {
+  try {
+    return require(`${name}/package.json`).version;
+  } catch {
+    return null;
+  }
+}
+
+function binaryVersionOf(binPath) {
+  // Ask the binary its version. `--version` prints and exits BEFORE the license gate,
+  // so this works without a configured license. Returns null if it can't be read.
+  try {
+    const out = execFileSync(binPath, ['--version'],
+      { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] });
+    return out.trim() || null;
+  } catch (e) {
+    const out = ((e.stdout || '') + (e.stderr || '')).trim();
+    return out || null;
+  }
+}
+
+function licenseSource() {
+  // Where the key is configured (env / file), with NO server call. null if unset.
+  if (process.env.CAPIUM_LICENSE_KEY) return 'env CAPIUM_LICENSE_KEY';
+  const { key } = license._fromFile(); // ~/.capium/license
+  return key ? '~/.capium/license' : null;
+}
+
+async function gather(quick) {
+  const info = { issues: [] };
+  info.sdk = { version: SDK_VERSION, targets_chromium: CAPIUM_BINARY_VERSION };
+  info.node = { version: process.version, os: process.platform, arch: os.arch() };
+
+  const pwv = driverVersion('playwright-core') || driverVersion('playwright');
+  const ppv = driverVersion('puppeteer-core') || driverVersion('puppeteer');
+  info.drivers = {
+    'playwright-core': pwv,
+    'puppeteer-core': ppv,
+  };
+  if (!pwv && !ppv) {
+    info.issues.push('No driver installed  ->  npm install playwright-core (or puppeteer-core)');
+  }
+
+  const binary = { found: false, path: null, version: null, installed_version: null,
+    target_version: CAPIUM_BINARY_VERSION, up_to_date: null, platform_tag: null };
+  try {
+    binary.platform_tag = download.downloadTag();
+  } catch (e) { // unsupported platform (macOS Intel, Windows ARM)
+    binary.platform_error = e.message;
+    info.issues.push(e.message);
+  }
+  try {
+    const binPath = config.findBinary();
+    const vstr = binaryVersionOf(binPath); // e.g. "Capium 152.0.7977.65"
+    const m = /\d+\.\d+\.\d+\.\d+/.exec(vstr || '');
+    const iv = m ? m[0] : download.installedVersion(binPath); // marker fallback
+    binary.found = true;
+    binary.path = binPath;
+    binary.version = vstr;
+    binary.installed_version = iv;
+    binary.up_to_date = iv ? iv === CAPIUM_BINARY_VERSION : null;
+    if (iv && iv !== CAPIUM_BINARY_VERSION) {
+      info.issues.push(
+        `Browser binary is ${iv} but the SDK targets ${CAPIUM_BINARY_VERSION}  ->  it ` +
+          'auto-updates on the next launch (or run: npx capiumbrowser install)');
+    }
+  } catch {
+    info.issues.push('Browser binary not installed  ->  npx capiumbrowser install');
+  }
+  info.binary = binary;
+
+  const src = licenseSource();
+  const lic = { configured: src !== null, source: src, server_checked: false,
+    plan: null, sessions_cap: null, live_sessions: null, period_end: null };
+  if (src === null) {
+    info.issues.push('No license key  ->  set CAPIUM_LICENSE_KEY or ~/.capium/license (KEY=...)');
+  } else if (!quick) {
+    try {
+      const st = await license.status();
+      Object.assign(lic, { server_checked: true, plan: st.plan,
+        sessions_cap: st.sessions_cap, live_sessions: st.live_sessions,
+        period_end: st.period_end });
+    } catch (e) {
+      lic.server_error = e.message;
+      info.issues.push(`License check failed  ->  ${e.message}`);
+    }
+  }
+  info.license = lic;
+  return info;
+}
+
+function printHuman(info) {
+  const row = (label, val, status) => {
+    const tag = status === undefined ? '' : `  [${status}]`;
+    console.log(`  ${label.padEnd(13)} ${val}${tag}`);
+  };
+
+  console.log('\nCapium browser -- environment check\n');
+  row('SDK', `capiumbrowser ${info.sdk.version}  (targets Chromium ${info.sdk.targets_chromium})`);
+  row('Node', `${info.node.version} on ${info.node.os}/${info.node.arch}`);
+  const d = info.drivers;
+  row('Playwright', d['playwright-core'] || 'not installed',
+    d['playwright-core'] ? 'OK' : 'missing');
+  row('Puppeteer', d['puppeteer-core'] || 'not installed',
+    d['puppeteer-core'] ? 'OK' : 'missing');
+
+  const b = info.binary;
+  console.log();
+  if (b.platform_tag) row('Platform', `${b.platform_tag}  (${info.node.os}/${info.node.arch})`);
+  else if (b.platform_error) {
+    row('Platform', `unsupported: ${info.node.os}/${info.node.arch}`, 'UNSUPPORTED');
+  }
+  if (b.found) {
+    const iv = b.installed_version;
+    if (iv && b.up_to_date) row('Binary', `installed  v${iv}  (up to date)`, 'OK');
+    else if (iv) {
+      row('Binary',
+        `installed  v${iv}  ->  SDK targets v${b.target_version} (auto-updates next launch)`,
+        'UPDATE');
+    } else row('Binary', 'installed', 'OK');
+    row('', b.path);
+  } else {
+    row('Binary', 'NOT INSTALLED', 'MISSING');
+    row('', `target v${b.target_version}  ->  npx capiumbrowser install`);
+  }
+
+  const lic = info.license;
+  console.log();
+  if (lic.configured) {
+    row('License', `key from ${lic.source}`, 'OK');
+    if (lic.server_checked) {
+      row('', `plan=${lic.plan}  seats=${lic.sessions_cap} (${lic.live_sessions} live)  ` +
+        `renews=${lic.period_end}`);
+    } else if (lic.server_error) row('', `server check: ${lic.server_error}`, 'WARN');
+  } else {
+    row('License', 'not configured', 'MISSING');
+  }
+
+  console.log();
+  if (info.issues.length) {
+    console.log(`${info.issues.length} thing(s) to fix:`);
+    for (const i of info.issues) console.log(`  - ${i}`);
+  } else {
+    console.log('Ready: everything needed is installed and configured.');
+  }
+  console.log();
+}
+
+// ---- subcommands -------------------------------------------------------------
+
+async function cmdInfo(flags) {
+  const info = await gather(flags.includes('--quick'));
+  if (flags.includes('--json')) console.log(JSON.stringify(info, null, 2));
+  else printHuman(info);
+  return info.issues.length ? 1 : 0;
+}
+
+async function cmdStatus(flags) {
+  let st;
+  try {
+    st = await license.status();
+  } catch (e) {
+    console.error(`capiumbrowser status: ${e.message}`);
+    return 1;
+  }
+  if (flags.includes('--json')) console.log(JSON.stringify(st, null, 2));
+  else for (const [k, v] of Object.entries(st)) console.log(`  ${k.padEnd(14)} ${v}`);
+  return 0;
+}
+
+function cmdVersion() {
+  console.log(`capiumbrowser ${SDK_VERSION} (targets Chromium ${CAPIUM_BINARY_VERSION})`);
+  try {
+    const binPath = config.findBinary();
+    const vstr = binaryVersionOf(binPath) || '';
+    const m = /\d+\.\d+\.\d+\.\d+/.exec(vstr);
+    const iv = m ? m[0] : (download.installedVersion(binPath) || 'unknown');
+    if (iv === CAPIUM_BINARY_VERSION) {
+      console.log(`installed binary: v${iv} (up to date) at ${binPath}`);
+    } else {
+      console.log(
+        `installed binary: v${iv} -> updates to v${CAPIUM_BINARY_VERSION} on next launch, ` +
+          `at ${binPath}`);
+    }
+  } catch {
+    console.log('installed binary: NOT INSTALLED -> npx capiumbrowser install');
+  }
+  return 0;
+}
+
+async function cmdInstall() {
+  const { key } = license.effective();
+  console.log('downloading the capium browser binary ...');
+  console.log('installed:', await download.ensureBinary({ licenseKey: key }));
+  return 0;
+}
+
+async function cmdRun(url) {
+  const seed = process.env.SEED;
+  const geoipEnv = process.env.GEOIP; // 1 = force on, 0 = force off, unset = auto (null)
+  const opts = {
+    seed: seed ? Number(seed) : null,
+    platform: process.env.PLATFORM || 'windows',
+    headless: process.env.HEADLESS === '1',
+    proxy: process.env.PROXY || null,
+    geoip: geoipEnv === '1' ? true : geoipEnv === '0' ? false : null,
+  };
+  const driver = require('../index').detectDriver();
+  const target = url || 'https://fingerprint.com/demo/';
+  let page;
+  let closer;
+  const profile = process.env.PROFILE;
+  if (profile) {
+    const ctx = await driver.launchPersistentContext(profile, opts);
+    closer = ctx;
+    const pages = typeof ctx.pages === 'function' ? await ctx.pages() : [];
+    page = pages[0] || (await ctx.newPage());
+    await page.goto(target, { waitUntil: 'domcontentloaded', timeout: 60000 });
+  } else {
+    const res = await driver.launchContext({
+      url: target, humanize: process.env.HUMANIZE === '1', ...opts,
+    });
+    page = res.page;
+    closer = res.browser;
+  }
+  console.log('== Capium ==');
+  console.log('  platform :', await page.evaluate(() => navigator.platform));
+  console.log('  userAgent:', await page.evaluate(() => navigator.userAgent));
+  console.log('  url      :', target);
+  console.log('Browser open. Ctrl-C to exit.');
+  await new Promise((resolve) => {
+    process.on('SIGINT', resolve);
+    process.on('SIGTERM', resolve);
+  });
+  await closer.close();
+  return 0;
+}
+
+async function main() {
+  const [cmd, ...restArgs] = process.argv.slice(2);
+  const flags = restArgs.filter((a) => a.startsWith('--'));
+  const positional = restArgs.filter((a) => !a.startsWith('--'));
+  try {
+    switch (cmd) {
+      case undefined:
+      case 'info':
+        // No subcommand -> the diagnostic, so a bare `npx capiumbrowser` is useful.
+        return await cmdInfo(flags);
+      case 'status':
+        return await cmdStatus(flags);
+      case 'version':
+        return cmdVersion();
+      case 'install':
+        return await cmdInstall();
+      case 'run':
+        return await cmdRun(positional[0]);
+      case '--help':
+      case '-h':
+      case 'help':
+        console.log(fs.readFileSync(__filename, 'utf8')
+          .split('\n').slice(1, 15).map((l) => l.replace(/^ \* ?/, '')).join('\n'));
+        return 0;
+      default:
+        console.error(`unknown command: ${cmd} (try: info, status, version, install, run)`);
+        return 2;
+    }
+  } catch (e) {
+    if (e instanceof CapiumError) {
+      console.error(`capiumbrowser: ${e.message}`);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+main().then((code) => process.exit(code));

package/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Type declarations for capiumbrowser.
+ *
+ * Driver return types are intentionally structural (`any`-compatible) so the package works
+ * with playwright-core OR puppeteer-core without depending on either's types. Cast the
+ * results to your driver's types at the call site if you want full IntelliSense:
+ *
+ *     import type { Browser } from 'playwright-core';
+ *     const browser = (await launch({ seed: 42 })) as unknown as Browser;
+ */
+
+export type Platform = 'windows' | 'macos' | 'linux';
+
+export interface ProxySpec {
+  /** "scheme://host:port" (http, https, socks5). */
+  server: string;
+  username?: string;
+  password?: string;
+  /** Comma-separated hosts/patterns that connect DIRECT, skipping the proxy. */
+  bypass?: string;
+}
+
+export interface LaunchOptions {
+  /** Identity seed (a stable, coherent device per seed). Random if omitted. */
+  seed?: number | null;
+  /** The spoofed OS persona. Default "windows". */
+  platform?: Platform;
+  /** Default false (a windowed browser is the coherent persona default). */
+  headless?: boolean;
+  /** "http://user:pass@host:port" | "socks5://host:port" | ProxySpec. */
+  proxy?: string | ProxySpec | null;
+  /**
+   * Geo coherence, resolved inside the binary. null/undefined (default) = OFF: no lookup
+   * runs, even with a proxy. true = pin timezone/geo/WebRTC/language to the egress.
+   * false = explicit opt-out.
+   */
+  geoip?: boolean | null;
+  /** Extra Chromium args appended after the stealth flags. */
+  args?: string[] | null;
+  /** false drops the default fingerprint flags. Default true. */
+  stealthArgs?: boolean;
+  /** IANA timezone override (in-binary spoof), e.g. "Europe/Berlin". */
+  timezone?: string | null;
+  /** BCP-47 locale override, e.g. "de-DE". */
+  locale?: string | null;
+  /** Unpacked extension dir(s) to load. */
+  extensionPaths?: string | string[] | null;
+  /** Explicit path to the capium launch target (skips discovery + download). */
+  binary?: string | null;
+  /** License key (else CAPIUM_LICENSE_KEY / ~/.capium/license). Never lands on argv. */
+  licenseKey?: string | null;
+  licenseServer?: string | null;
+  /** Route the binary's license traffic through the configured proxy. */
+  licenseThroughProxy?: boolean;
+  /** Fail fast (offline) with CapiumConfigError when no key is set. Default true. */
+  licensePreflight?: boolean;
+  /** Any remaining options are forwarded to the driver's launch(). */
+  [driverOption: string]: unknown;
+}
+
+export interface LaunchContextOptions extends LaunchOptions {
+  /** Navigate the first page here (domcontentloaded). */
+  url?: string | null;
+  /** Attach page.humanMove/humanClick/humanType/humanScroll helpers. */
+  humanize?: boolean;
+  humanPreset?: 'default' | 'careful';
+}
+
+export class CapiumError extends Error {}
+export class CapiumLicenseError extends CapiumError {}
+export class CapiumConfigError extends CapiumLicenseError {}
+export class CapiumSeatLimitError extends CapiumLicenseError {}
+export class CapiumExpiredError extends CapiumLicenseError {}
+export class CapiumServerDownError extends CapiumLicenseError {}
+
+export const VERSION: string;
+export const CAPIUM_BINARY_VERSION: string;
+export const CAPIUM_BINARY_VERSIONS: Record<string, string>;
+
+/**
+ * Escape hatch (on the capiumbrowser/playwright and capiumbrowser/puppeteer subpaths):
+ * the ready-made options object for the driver's own launch(), for framework
+ * integrations that must hold the launch themselves.
+ */
+export function buildLaunchOptions(options?: LaunchOptions): Promise<Record<string, unknown>>;
+
+/** Launch a Capium Browser via the installed driver (Playwright preferred when both are). */
+export function launch(options?: LaunchOptions): Promise<any>;
+export function launchContext(options?: LaunchContextOptions):
+  Promise<{ browser: any; context?: any; page: any }>;
+export function launchPersistentContext(userDataDir: string, options?: LaunchOptions):
+  Promise<any>;
+export function detectDriver(): {
+  launch: typeof launch;
+  launchContext: typeof launchContext;
+  launchPersistentContext: typeof launchPersistentContext;
+};
+
+export function status(licenseKey?: string | null, licenseServer?: string | null):
+  Promise<{ plan: string | null; sessions_cap: number | null; live_sessions: number | null;
+    period_end: string | null; heartbeat_every: number | null }>;
+
+export namespace config {
+  function getDefaultStealthArgs(seed?: number | null, platform?: Platform,
+    screen?: [number, number] | null): string[];
+  function newSeed(): number;
+  function findBinary(binary?: string | null): string;
+}
+
+export namespace proxy {
+  function buildProxyArg(spec: string | ProxySpec | null | false): string | null;
+  function resolveProxyConfig(spec: string | ProxySpec | null | false,
+    inlineAuth?: boolean | null): { launchOptions: object; args: string[] };
+}
+
+export namespace download {
+  function downloadTag(system?: string | null, machine?: string | null): string;
+  function distroPath(version: string, tag: string): string;
+  function ensureBinary(opts?: { version?: string | null; licenseKey?: string | null;
+    server?: string | null }): Promise<string>;
+  function installedVersion(binPath?: string | null): string | null;
+}
+
+export namespace human {
+  function humanize<T>(target: T, preset?: 'default' | 'careful'): T;
+  function move(page: any, x: number, y: number, preset?: string): Promise<void>;
+  function click(page: any, selector: string, preset?: string): Promise<void>;
+  function typeText(page: any, selector: string, text: string, preset?: string): Promise<void>;
+  function scroll(page: any, dy: number, preset?: string): Promise<void>;
+  function dwell(loSec?: number, hiSec?: number): Promise<void>;
+}