capiumbrowser 0.1.0

package/lib/download.js

@@ -0,0 +1,364 @@
+/**
+ * download -- fetch/extract the per-platform Capium binary if it isn't already present.
+ *
+ * The Node SDK and the browser binary are decoupled: update playwright-core/puppeteer-core with
+ * npm, and fetch the matching Capium build separately. If the launch target isn't found locally,
+ * ensureBinary() downloads the per-platform tarball and extracts it under ~/.capium (CAPIUM_HOME
+ * overrides).
+ *
+ * Download scheme (signed, path-based):
+ *     GET {server}/download/distro/chromium-v{version}/capiumbrowser-{os}-{arch}.tar.gz
+ *
+ * The license key travels in the X-Capzy-License header (over TLS), NEVER in the URL; the
+ * request PATH is HMAC-signed (X-Capzy-Timestamp + X-Capzy-Signature =
+ * HMAC-SHA256(key, "<ts>.<path>")) -- the same scheme as the licensing calls. The response's
+ * X-Capzy-SHA256 is verified against the downloaded bytes before anything is extracted.
+ *
+ * The archive FILENAME is version-independent -- `capiumbrowser-<os>-<arch>.tar.gz` is always
+ * the same; only the `chromium-v<version>/` folder changes.
+ *
+ * Source resolution (first that works):
+ *     CAPIUM_BINARY            -> use this exact launch target, no download
+ *     CAPIUM_DOWNLOAD_URL      -> a direct .tar.gz URL (may contain {platform}/{version}); unsigned escape hatch
+ *     license server           -> the signed GET above
+ *
+ * Supported platforms (the four capium publishes):
+ *     linux-x64   linux-arm64   windows-x64   macos-arm64
+ * Anything else (macOS Intel, Windows ARM, ...) throws a clear CapiumError.
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { pipeline } = require('stream/promises');
+const { Readable, Transform } = require('stream');
+
+const tar = require('tar');
+
+const config = require('./config');
+const license = require('./license');
+const { CapiumError, CapiumExpiredError, CapiumServerDownError } = require('./errors');
+const { binaryVersionFor, isPublished } = require('./version');
+
+const NET_TIMEOUT_MS = 300000;
+
+// (normalized os, normalized arch) -> distro tag used in the filename/URL.
+const SUPPORTED = {
+  'linux/x64': 'linux-x64',
+  'linux/arm64': 'linux-arm64',
+  'windows/x64': 'windows-x64',
+  'macos/arm64': 'macos-arm64',
+};
+
+function normOs(sysname) {
+  const s = String(sysname).toLowerCase();
+  if (s === 'darwin') return 'macos';
+  if (s === 'windows' || s === 'win32') return 'windows';
+  return 'linux';
+}
+
+function normArch(mach) {
+  const m = String(mach).toLowerCase();
+  if (['x86_64', 'amd64', 'x64'].includes(m)) return 'x64';
+  if (['arm64', 'aarch64'].includes(m)) return 'arm64';
+  return m;
+}
+
+/**
+ * The distro tag for THIS host -- one of linux-x64, linux-arm64, windows-x64, macos-arm64.
+ *
+ * Throws CapiumError for a platform capium doesn't publish (e.g. macOS Intel, Windows ARM).
+ */
+function downloadTag(system = null, machine = null) {
+  const os_ = normOs(system || process.platform);
+  const arch = normArch(machine || os.arch());
+  const tag = SUPPORTED[`${os_}/${arch}`];
+  if (!tag) {
+    throw new CapiumError(
+      `capium has no build for this platform: ${os_}/${arch} ` +
+        `(${system || process.platform} ${machine || os.arch()}). ` +
+        `Supported: ${Object.values(SUPPORTED).sort().join(', ')}.`);
+  }
+  return tag;
+}
+
+/**
+ * The signed request path for a build. Filename is version-independent; only the folder
+ * carries the version (per the '...end name will all be the same' contract).
+ */
+function distroPath(version, tag) {
+  return `/download/distro/chromium-v${version}/capiumbrowser-${tag}.tar.gz`;
+}
+
+// ---- extraction ------------------------------------------------------------------------------
+
+/** Where extracted distros live: CAPIUM_HOME, else ~/.capium (survives an npm reinstall). */
+function destRoot() {
+  return process.env.CAPIUM_HOME || path.join(os.homedir(), '.capium');
+}
+
+/**
+ * Extract a distro archive, sniffing gzip/zip/tar so the server can ship any of them.
+ *
+ * Extracts into a scratch dir first, then normalizes: a single-top archive (the tar layout,
+ * e.g. `capium-152-linux-x64/...`) lands as `root/<thatdir>`; a FLAT archive (a Windows tar
+ * whose `chrome.exe` / `locales/` sit at the root) is wrapped into `root/<subdir>` so it
+ * stays discoverable. Returns the extracted distro directory.
+ */
+async function extract(archivePath, root, subdir) {
+  const magic = Buffer.alloc(4);
+  const fd = fs.openSync(archivePath, 'r');
+  try {
+    fs.readSync(fd, magic, 0, 4, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  const scratch = fs.mkdtempSync(path.join(root, '.capium-extract-'));
+  try {
+    if (magic[0] === 0x50 && magic[1] === 0x4b && magic[2] === 0x03 && magic[3] === 0x04) {
+      // zip: no zip support in the `tar` package -- use the system bsdtar (ships with
+      // Windows 10+/macOS; on Linux the server contract is tar.gz so this path is rare).
+      try {
+        execFileSync('tar', ['-xf', archivePath, '-C', scratch], { stdio: 'ignore' });
+      } catch (e) {
+        throw new CapiumError(
+          `the server sent a zip archive but this host's \`tar\` could not extract it (${e.message}). ` +
+            'Install bsdtar/unzip or set CAPIUM_DOWNLOAD_URL to a .tar.gz build.');
+      }
+    } else {
+      // gzip / plain tar -- the tar package sniffs compression itself.
+      await tar.x({ file: archivePath, cwd: scratch });
+    }
+    const entries = fs.readdirSync(scratch);
+    if (entries.length === 1 &&
+        fs.statSync(path.join(scratch, entries[0])).isDirectory()) {
+      // single top-level dir: the archive carries its own capium-*/ folder
+      const target = path.join(root, entries[0]);
+      fs.rmSync(target, { recursive: true, force: true });
+      fs.renameSync(path.join(scratch, entries[0]), target);
+      return target;
+    }
+    // flat archive: wrap it so discovery (capium-*/ glob) still finds it
+    const target = path.join(root, subdir);
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(scratch, target);
+    return target;
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+const MARKER = '.capium-build';
+
+/**
+ * Read the build version stamped next to an installed binary, or null (an old install
+ * from before version-stamping, which we treat as 'unknown' -> upgrade it).
+ */
+function readInstalledVersion(binPath) {
+  try {
+    return fs.readFileSync(path.join(path.dirname(binPath), MARKER), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Public: the stamped build version of the installed capium binary, or null if it isn't
+ * installed / wasn't version-stamped. `binPath` defaults to the discovered binary.
+ */
+function installedVersion(binPath = null) {
+  if (binPath === null) {
+    try {
+      binPath = config.findBinary();
+    } catch {
+      return null;
+    }
+  }
+  return readInstalledVersion(binPath);
+}
+
+function stampVersion(binPath, version) {
+  try {
+    fs.writeFileSync(path.join(path.dirname(binPath), MARKER), String(version));
+  } catch {}
+}
+
+/**
+ * Delete previously-extracted capium distros under `root`. A host only ever holds its own
+ * platform's build, so on a version change we drop the stale one before installing the new
+ * one ('old removed, new downloaded'). Never touches CAPIUM_BINARY / PATH targets outside
+ * `root`.
+ */
+function removeInstalls(root) {
+  let names;
+  try {
+    names = fs.readdirSync(root);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    if (!n.startsWith('capium-')) continue;
+    const d = path.join(root, n);
+    try {
+      if (fs.statSync(d).isDirectory()) fs.rmSync(d, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+// ---- download --------------------------------------------------------------------------------
+
+/**
+ * Stream `url` to `dest`, mapping transport failures to typed errors and verifying the
+ * server's X-Capzy-SHA256 against the bytes. Returns the hex sha256.
+ */
+async function download(url, headers, dest, version, tag) {
+  let res;
+  try {
+    res = await fetch(url, { headers: headers || {}, signal: AbortSignal.timeout(NET_TIMEOUT_MS) });
+  } catch (e) {
+    throw new CapiumServerDownError(
+      `could not reach the download server ${url}: ${e.cause?.message || e.message || e}`);
+  }
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new CapiumError(
+        `no capium build published for version ${version} on ${tag} (HTTP 404). Check ` +
+          'CAPIUM_VERSION, or that this platform/version is published.');
+    }
+    if (res.status === 401 || res.status === 403) {
+      throw new CapiumExpiredError(
+        `license rejected while downloading (HTTP ${res.status}) -- expired, revoked, or ` +
+          'invalid key. Run `npx capiumbrowser status` to check.');
+    }
+    throw new CapiumServerDownError(`download failed: HTTP ${res.status} from ${url}`);
+  }
+  const expected = res.headers.get('x-capzy-sha256');
+  const hash = crypto.createHash('sha256');
+  const hasher = new Transform({
+    transform(chunk, _enc, cb) {
+      hash.update(chunk);
+      cb(null, chunk);
+    },
+  });
+  await pipeline(Readable.fromWeb(res.body), hasher, fs.createWriteStream(dest));
+  const got = hash.digest('hex').toLowerCase();
+  if (expected && got !== expected.toLowerCase()) {
+    throw new CapiumError(
+      'capium download failed its integrity check (sha256 mismatch): expected ' +
+        `${expected.toLowerCase()}, got ${got} (corrupted or tampered download).`);
+  }
+  return got;
+}
+
+/**
+ * Return the path to the capium launch target, downloading + extracting the per-platform
+ * build if it isn't already present.
+ *
+ * Throws:
+ *     CapiumError          -- unsupported platform, version/platform not published (404), or a
+ *                             sha256 integrity failure.
+ *     CapiumConfigError    -- no license key configured and no other source (from resolve()).
+ *     CapiumExpiredError   -- the license was rejected (401/403).
+ *     CapiumServerDownError-- the download server was unreachable / 5xx.
+ */
+async function ensureBinary({ version = null, licenseKey = null, server = null } = {}) {
+  // An explicit CAPIUM_BINARY path always wins -- it's the caller's choice, no version check.
+  if (process.env.CAPIUM_BINARY) return config.findBinary();
+
+  // Resolve the host's distro tag first: the default binary version is per-OS (each OS reaches
+  // a stable build independently), so we can't pick a default until we know which tag we're on.
+  const tag = downloadTag();
+
+  // If the manifest declares this OS but hasn't marked it published, say so plainly instead of
+  // letting the download 404. An explicit CAPIUM_VERSION means the caller knows a build exists,
+  // so we don't gate that path.
+  if (!version && !process.env.CAPIUM_VERSION && !isPublished(tag)) {
+    throw new CapiumError(
+      `capium has no stable build published for ${tag} yet (declared but not yet released). ` +
+        'Set CAPIUM_VERSION to pin a specific build if one exists.');
+  }
+
+  version = version || process.env.CAPIUM_VERSION || binaryVersionFor(tag);
+
+  // Reuse the cached binary ONLY if it's already the target version. A different (older)
+  // version -- e.g. after `npm install capiumbrowser@latest` bumps this OS's pinned build --
+  // falls through to fetch the new build and drop the old one.
+  try {
+    const existing = config.findBinary();
+    if (readInstalledVersion(existing) === version) return existing;
+  } catch {}
+
+  let url;
+  let headers = null;
+  const direct = process.env.CAPIUM_DOWNLOAD_URL;
+  if (direct) {
+    url = direct.replaceAll('{platform}', tag).replaceAll('{version}', version);
+  } else {
+    // Signed path-based download: key in a header, PATH HMAC-signed, sha256-verified.
+    const { key, server: srv } = license.resolve(licenseKey, server); // -> CapiumConfigError if no key
+    const p = distroPath(version, tag);
+    url = srv + p;
+    headers = license.getHeaders(key, p);
+  }
+
+  const root = destRoot();
+  fs.mkdirSync(root, { recursive: true });
+  const subdir = `capium-${String(version).split('.')[0]}-${tag}`; // FLAT-archive wrapper name
+  const tmp = path.join(os.tmpdir(),
+    `capium-dl-${crypto.randomBytes(6).toString('hex')}.tar.gz`);
+  try {
+    await download(url, headers, tmp, version, tag);
+    // Only drop the stale install once the new bytes are in hand (a failed download must
+    // never leave the host with no binary), then extract the new version.
+    removeInstalls(root);
+    const distroDir = await extract(tmp, root, subdir);
+    // Stamp the version marker BEFORE discovery: the FLAT Windows tar carries no capium
+    // marker files, and findBinary only accepts a bare chrome.exe next to one -- the
+    // downloader vouches for the directory it just extracted.
+    try {
+      fs.writeFileSync(path.join(distroDir, MARKER), String(version));
+    } catch {}
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {}
+  }
+
+  let binPath;
+  try {
+    binPath = config.findBinary();
+  } catch {
+    throw new CapiumError(
+      `downloaded and extracted the ${tag} build but no launch target was found afterwards ` +
+        `(unexpected archive layout under ${root}).`);
+  }
+  stampVersion(binPath, version); // so a later version bump knows to re-download
+  // Re-apply exec bits the wrapper + engine binaries need (zip drops unix perms).
+  if (process.platform !== 'win32') {
+    for (const p of [binPath, path.join(path.dirname(binPath), 'chrome')]) {
+      try {
+        fs.chmodSync(p, 0o755);
+      } catch {}
+    }
+  }
+  return binPath;
+}
+
+module.exports = {
+  downloadTag,
+  distroPath,
+  destRoot,
+  ensureBinary,
+  installedVersion,
+  _SUPPORTED: SUPPORTED,
+  _normOs: normOs,
+  _normArch: normArch,
+  _extract: extract,
+  _removeInstalls: removeInstalls,
+  _readInstalledVersion: readInstalledVersion,
+  _stampVersion: stampVersion,
+  _download: download,
+};

package/lib/errors.js

@@ -0,0 +1,114 @@
+/**
+ * Typed errors, chiefly for licensing.
+ *
+ * Enforcement lives in the browser binary; when it refuses to start it prints a
+ * `[capium-license] ...` line to stderr and exits with a coded status. Playwright's /
+ * Puppeteer's native launch surfaces that stderr inside its own launch error --
+ * `translateLaunchError` turns it into a precise, actionable capium exception.
+ */
+'use strict';
+
+const fs = require('fs');
+
+/** Base class for capium SDK errors. */
+class CapiumError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/** The browser refused to start for a licensing reason. */
+class CapiumLicenseError extends CapiumError {}
+
+/** No license key configured. */
+class CapiumConfigError extends CapiumLicenseError {}
+
+/** Concurrent session limit reached across the owner's machines. */
+class CapiumSeatLimitError extends CapiumLicenseError {}
+
+/** License expired, revoked, or the key is invalid. */
+class CapiumExpiredError extends CapiumLicenseError {}
+
+/** License service unreachable and no valid offline grace. */
+class CapiumServerDownError extends CapiumLicenseError {}
+
+function clean(msg) {
+  // Pull the '[capium-license] ...' line out of a noisy launch error, if present.
+  for (const line of String(msg).split(/\r?\n/)) {
+    if (line.includes('[capium-license]')) {
+      return line.split('[capium-license]')[1].trim();
+    }
+  }
+  return String(msg).trim();
+}
+
+/**
+ * Map a driver launch failure to a typed license error when the browser's fail-closed
+ * stderr is recognizable. Returns a new error to throw, or null if this isn't a
+ * licensing failure (caller should re-throw the original).
+ */
+function translateLaunchError(err) {
+  const low = String(err && err.message ? err.message : err).toLowerCase();
+  if (!low.includes('capium-license') && !low.includes('no license configured')) return null;
+  const hint = clean(err && err.message ? err.message : err);
+  if (low.includes('no license configured')) {
+    return new CapiumConfigError(
+      `${hint}\nSet CAPIUM_LICENSE_KEY, pass licenseKey: ..., or create ` +
+        '~/.capium/license (KEY=). Run `npx capiumbrowser status` to check.');
+  }
+  if (low.includes('session limit') || low.includes('concurrent session')) {
+    return new CapiumSeatLimitError(`${hint} — close another Capium browser and retry.`);
+  }
+  if (low.includes('rejected') || low.includes('expired') || low.includes('revoked')) {
+    return new CapiumExpiredError(hint);
+  }
+  if (low.includes('unreachable') || low.includes('offline grace')) {
+    return new CapiumServerDownError(hint);
+  }
+  return new CapiumLicenseError(hint);
+}
+
+// Exit codes written by the binary's fail-closed path (capium_license_main_extra_parts.cc).
+const STATUS_CODES = {
+  2: CapiumConfigError, // kExitNoLicense
+  3: CapiumSeatLimitError, // kExitSeatLimit
+  4: CapiumExpiredError, // kExitExpired (expired / revoked / bad key)
+  5: CapiumServerDownError, // kExitServerDown
+};
+
+/**
+ * Turn the binary's fail-closed status file into a typed error, or null.
+ *
+ * On a licensing fail-closed the binary writes "<exit_code>\n<message>" to the path the SDK
+ * handed it via CAPIUM_LICENSE_STATUS_FILE. Reading THAT is how we surface a precise error
+ * from the binary's OWN single verification -- no second server call, and reliable where the
+ * driver's stderr relay (translateLaunchError) isn't. Returns null when the file is
+ * absent/empty (old binary that doesn't write it -> stderr fallback).
+ */
+function readLaunchStatus(statusPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(statusPath, 'utf8');
+  } catch {
+    return null;
+  }
+  if (!raw.trim()) return null;
+  const nl = raw.indexOf('\n');
+  const code = (nl === -1 ? raw : raw.slice(0, nl)).trim();
+  const msg = (nl === -1 ? '' : raw.slice(nl + 1)).trim() ||
+    'the browser refused to start for a licensing reason';
+  const Cls = STATUS_CODES[code] || CapiumLicenseError;
+  return new Cls(msg);
+}
+
+module.exports = {
+  CapiumError,
+  CapiumLicenseError,
+  CapiumConfigError,
+  CapiumSeatLimitError,
+  CapiumExpiredError,
+  CapiumServerDownError,
+  translateLaunchError,
+  readLaunchStatus,
+};

package/lib/human.js

@@ -0,0 +1,142 @@
+/**
+ * human -- realistic mouse / typing / scroll for Playwright AND Puppeteer pages.
+ *
+ * Anti-bot systems increasingly score *behavior*: instant teleport-clicks, zero-jitter typing
+ * and single-delta scrolls are bot tells. These helpers move the cursor along a bezier path
+ * with variable speed, type with per-key jitter, and scroll in eased increments. Pure driver
+ * input (page.mouse / page.keyboard) -- no CDP tricks, so it stays consistent with the stealth
+ * binary. The Playwright and Puppeteer input APIs align on everything used here except
+ * mouse.wheel, which is bridged below.
+ *
+ * Presets tune the timing:
+ *     "default" -> natural human pace
+ *     "careful" -> slower, more deliberate (harder to flag, but slower runs)
+ */
+'use strict';
+
+const PRESETS = {
+  default: { moveSteps: [18, 34], stepMs: [6, 16], keyMs: [45, 130],
+    clickPauseMs: [40, 140], scrollStep: [90, 220], scrollMs: [30, 90] },
+  careful: { moveSteps: [30, 55], stepMs: [12, 28], keyMs: [80, 220],
+    clickPauseMs: [120, 320], scrollStep: [50, 130], scrollMs: [60, 150] },
+};
+
+const cfg = (preset) => PRESETS[preset] || PRESETS.default;
+const rand = (lo, hi) => lo + Math.random() * (hi - lo);
+const randMs = ([lo, hi]) => rand(lo, hi);
+const randInt = (lo, hi) => Math.round(rand(lo, hi));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function pos(page) {
+  return page._capiumMouse || [randInt(2, 60), randInt(2, 60)];
+}
+
+function bezier(x0, y0, x1, y1, steps) {
+  // two random control points -> a curved, non-linear path
+  const cx1 = x0 + (x1 - x0) * rand(0.2, 0.45) + rand(-40, 40);
+  const cy1 = y0 + (y1 - y0) * rand(0.2, 0.45) + rand(-40, 40);
+  const cx2 = x0 + (x1 - x0) * rand(0.55, 0.8) + rand(-40, 40);
+  const cy2 = y0 + (y1 - y0) * rand(0.55, 0.8) + rand(-40, 40);
+  const pts = [];
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps;
+    const mt = 1 - t;
+    pts.push([
+      mt ** 3 * x0 + 3 * mt ** 2 * t * cx1 + 3 * mt * t ** 2 * cx2 + t ** 3 * x1,
+      mt ** 3 * y0 + 3 * mt ** 2 * t * cy1 + 3 * mt * t ** 2 * cy2 + t ** 3 * y1,
+    ]);
+  }
+  return pts;
+}
+
+async function wheel(page, dx, dy) {
+  // Playwright: mouse.wheel(dx, dy). Puppeteer: mouse.wheel({deltaX, deltaY}).
+  if (page.mouse.wheel.length >= 2) return page.mouse.wheel(dx, dy);
+  return page.mouse.wheel({ deltaX: dx, deltaY: dy });
+}
+
+/** Move the cursor to (x, y) along a human-like curved path. */
+async function move(page, x, y, preset = 'default') {
+  const c = cfg(preset);
+  const [x0, y0] = pos(page);
+  const steps = randInt(...c.moveSteps);
+  for (const [px, py] of bezier(x0, y0, x, y, steps)) {
+    await page.mouse.move(px, py);
+    await sleep(randMs(c.stepMs));
+  }
+  page._capiumMouse = [x, y];
+}
+
+/** Move to a random point inside `selector` and click with a natural pause. */
+async function click(page, selector, preset = 'default') {
+  const c = cfg(preset);
+  const el = await page.waitForSelector(selector, { state: 'visible', visible: true });
+  const box = await el.boundingBox();
+  const tx = box.x + box.width * rand(0.3, 0.7);
+  const ty = box.y + box.height * rand(0.3, 0.7);
+  await move(page, tx, ty, preset);
+  await sleep(randMs(c.clickPauseMs));
+  await page.mouse.down();
+  await sleep(rand(30, 90));
+  await page.mouse.up();
+}
+
+/** Click the field, then type with per-key jitter (occasional longer pauses). */
+async function typeText(page, selector, text, preset = 'default') {
+  const c = cfg(preset);
+  await click(page, selector, preset);
+  for (const ch of text) {
+    await page.keyboard.type(ch);
+    let d = randMs(c.keyMs);
+    if (Math.random() < 0.06) d += rand(150, 500); // occasional think-pause
+    await sleep(d);
+  }
+}
+
+/** Scroll `dy` pixels (positive = down) in eased increments, not one jump. */
+async function scroll(page, dy, preset = 'default') {
+  const c = cfg(preset);
+  let remaining = dy;
+  const direction = dy >= 0 ? 1 : -1;
+  while (Math.abs(remaining) > 1) {
+    const step = Math.min(Math.abs(remaining), rand(...c.scrollStep)) * direction;
+    await wheel(page, 0, step);
+    remaining -= step;
+    await sleep(randMs(c.scrollMs));
+  }
+}
+
+/** Idle a human-plausible moment (reading/hesitating). */
+async function dwell(loSec = 0.4, hiSec = 1.8) {
+  await sleep(rand(loSec * 1000, hiSec * 1000));
+}
+
+/**
+ * Attach page.humanMove / humanClick / humanType / humanScroll / humanDwell.
+ *
+ * target may be a Page or a BrowserContext (all current + future pages are patched).
+ * Returns target (chainable). Does NOT override page.click/type so existing code is safe;
+ * call the human* methods where you want human behavior.
+ */
+function humanize(target, preset = 'default') {
+  const attach = (page) => {
+    if (page._capiumHumanized) return;
+    page._capiumHumanized = true;
+    page.humanMove = (x, y, p = preset) => move(page, x, y, p);
+    page.humanClick = (sel, p = preset) => click(page, sel, p);
+    page.humanType = (sel, text, p = preset) => typeText(page, sel, text, p);
+    page.humanScroll = (dy, p = preset) => scroll(page, dy, p);
+    page.humanDwell = dwell;
+  };
+
+  // context: patch existing + hook new pages
+  if (typeof target.pages === 'function' && typeof target.on === 'function') {
+    for (const pg of target.pages()) attach(pg);
+    target.on('page', attach);
+  } else {
+    attach(target);
+  }
+  return target;
+}
+
+module.exports = { humanize, move, click, typeText, scroll, dwell, PRESETS };