captchakraken 2.6.1 → 2.9.0

package/README.md

@@ -19,6 +19,26 @@ nothing at all.
 > Full docs — demo videos, accuracy, self-hosting — live in the main repo
 > **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
 
+## Watch it work
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/hcaptcha_grid.webp" width="260"
+       alt="A live hCaptcha image select challenge being solved end to end">
+  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/recaptcha_4x4.webp" width="260"
+       alt="A live reCAPTCHA 4×4 tile grid challenge being solved end to end">
+  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/demo/geetest_slide.webp" width="260"
+       alt="A live GeeTest slide jigsaw challenge being solved end to end">
+</p>
+
+hCaptcha image select 12/12 in 10.5s · reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on **captcha-v12**
+against each vendor's own public demo page. Counts rather than percentages
+because ten attempts is not a percentage. Idle time is cut from the clips, so
+they run shorter than the solves they show.
+
+**Ten more puzzle types**, as video and with the full method, at
+[captchakraken.com](https://captchakraken.com) and in the
+[main repo](https://github.com/JWriter20/CaptchaKraken#watch-it-work).
+
 ## Install
 
 ```bash
@@ -83,15 +103,78 @@ await browser.close();
 
 Puppeteer users wrap the page once with `fromPuppeteer(page)`.
 
-## Configuration
+## How it moves — mouse, mobile, none, or yours
 
-| Variable | Meaning |
-|---|---|
-| `VLLM_BASE_URL` | Inference endpoint (local vLLM, a server you run, or `https://api.captchakraken.com/v1`) |
-| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) |
+Solving a captcha is two jobs: reading the puzzle, and *performing* the answer.
+The second is a choice of **input device**, not a realism dial.
+
+```typescript
+new CaptchaKrakenSolver({ humanization: 'mouse' })   // default
+new CaptchaKrakenSolver({ humanization: 'mobile' })  // real touch events
+new CaptchaKrakenSolver({ humanization: 'none' })    // straight to the DOM effect
+new CaptchaKrakenSolver({ humanizer: myOwn })        // yours; overrides the above
+```
+
+Unset, it reads `CAPTCHA_HUMANIZATION` and then falls back to `mouse` — which is
+byte-for-byte what the driver did before the option existed, so nothing moves for
+an existing caller. Anything set in code **wins** over the env var: which mode is
+right is a property of the page you are driving, not a deployment decision.
+
+`mobile` never touches `page.mouse`. A mousemove at a touch-only widget is the
+*wrong event*, not a weaker one — the page's touch handlers never fire and the
+solve fails for a reason nothing reports. It needs a Chromium-family page with
+touch turned on:
+
+```typescript
+import { chromium, devices } from 'playwright';
+
+const context = await browser.newContext({ ...devices['Pixel 7'], hasTouch: true });
+await new CaptchaKrakenSolver({ humanization: 'mobile' }).solve(await context.newPage());
+```
+
+Or drive a real handset over **Appium / WebdriverIO / Selenium** — gestures go
+out as W3C pointer actions with `pointerType: "touch"`:
+
+```typescript
+new CaptchaKrakenSolver({
+  humanization: 'mobile',
+  touchDriver: driver,                            // your Appium / WebdriverIO session
+  touchTransform: { scale: 3, origin: [0, 132] }, // CSS px -> screen px
+});
+```
+
+`touchTransform` is required rather than guessed: get it wrong and nothing
+raises — the action chain is valid, the device performs it, and the finger lands
+somewhere else. A `touchDriver` with no `scale` on a page reporting
+`devicePixelRatio !== 1` refuses on the first gesture and names the value to pass.
+
+Full details, including writing your own humanizer:
+[docs/usage.md § How it moves](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/usage.md#how-it-moves--mouse-mobile-none-or-yours).
+
+## Configuration
 
-Both fall back to `~/.captchakraken/credentials` when unset, so the hosted API
-needs no environment variables at all.
+| Variable | Meaning | Default |
+|---|---|---|
+| `VLLM_BASE_URL` | Inference endpoint (local vLLM, a server you run, or `https://api.captchakraken.com/v1`) | credentials file, else `http://localhost:8000/v1` |
+| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | credentials file, else `EMPTY` |
+| `CAPTCHA_HUMANIZATION` | How gestures are performed: `mouse`, `mobile` or `none`. Loses to anything set in code | `mouse` |
+| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `RedHatAI/Qwen3.5-9B-FP8-dynamic` |
+| `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken-Lora-v1.2` |
+| `CAPTCHA_LORA_NAME` | Served adapter name sent as `model` | `captcha-v12` |
+| `CAPTCHA_KRAKEN_AUTOSTART` | `0` never auto-starts a local server | `1` |
+| `CAPTCHA_KRAKEN_PYTHON` | Interpreter used for the bundled engine | the package's venv, else `python3` |
+| `CAPTCHA_KRAKEN_SKIP_PYTHON_SETUP` | `1` skips the `postinstall` bootstrap | unset |
+| `CAPTCHA_DEBUG` | `1` prints solver diagnostics to stderr | `0` |
+
+`VLLM_BASE_URL` and `CAPTCHA_KRAKEN_API_KEY` fall back to
+`~/.captchakraken/credentials` when unset, so the hosted API needs no
+environment variables at all.
+
+**Why the model and server variables appear here.** This package bundles the
+Python engine and spawns it, forwarding the environment wholesale — so every
+variable the engine reads applies to a TypeScript solve too. The full list, and
+the vLLM server knobs, are in
+[AGENTS.md § Environment variables](https://github.com/JWriter20/CaptchaKraken/blob/main/AGENTS.md#environment-variables).
 
 ## License
 

package/dist/cli-invocation.d.ts

@@ -1,26 +1,24 @@
 /**
  * How the JS client hands a solve request to the bundled Python CLI.
  *
- * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
- * line was then echoed:
+ * Two rules govern this module, and both exist because the alternative is
+ * unsafe rather than merely untidy:
  *
- *   console.log(`Executing CaptchaKraken CLI: ${command}`);
- *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
- *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
+ *    Argv is world-readable on Linux — any local user can read
+ *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
+ *    printed alongside the command lands in CI logs and terminal scrollback.
+ *    An environment block is per-process and not world-readable.
  *
- * Two leaks from one mistake. Argv is world-readable on Linux — any local user
- * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
- * the key was additionally written to stdout, so it landed in CI logs, terminal
- * scrollback, and anything scraping driver output.
- *
- * Secrets go through the environment instead, which is per-process and not
- * world-readable, and the command is built as an ARGV ARRAY for `execFile`
- * rather than a joined string for a shell, so a path with a space or a quote
- * cannot reshape the command.
+ * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
+ *    for a shell, so a screenshot path containing a space or a quote cannot
+ *    reshape the command.
  */
 /** Env var the CLI reads the bearer token from. */
 export declare const API_KEY_ENV = "CAPTCHA_KRAKEN_API_KEY";
-/** Historical positional placeholder. The CLI still accepts the slot. */
+/** Env var carrying the re-ask level for a board the vendor already refused. */
+export declare const RESAMPLE_LEVEL_ENV = "CAPTCHA_RESAMPLE_LEVEL";
+/** Positional placeholder the CLI still accepts in this slot. */
 export declare const API_PROVIDER = "captchaKrakenApi";
 export interface SolveInvocation {
     imagePath: string;
@@ -28,6 +26,8 @@ export interface SolveInvocation {
     puzzleSource: string;
     retryMode?: string | null;
     textMode?: boolean;
+    /** One expert of a routed model, or undefined to route by prompt family. */
+    expert?: string | null;
 }
 /**
  * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
@@ -35,7 +35,7 @@ export interface SolveInvocation {
  */
 export declare function buildSolveArgs(invocation: SolveInvocation): string[];
 /** Base env plus the credential, when there is one. */
-export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string): NodeJS.ProcessEnv;
+export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string, resampleLevel?: number): NodeJS.ProcessEnv;
 /**
  * A log line for a solve invocation, with any credential removed.
  *

package/dist/cli-invocation.js

@@ -2,38 +2,36 @@
 /**
  * How the JS client hands a solve request to the bundled Python CLI.
  *
- * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
- * line was then echoed:
+ * Two rules govern this module, and both exist because the alternative is
+ * unsafe rather than merely untidy:
  *
- *   console.log(`Executing CaptchaKraken CLI: ${command}`);
- *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
- *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
+ *    Argv is world-readable on Linux — any local user can read
+ *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
+ *    printed alongside the command lands in CI logs and terminal scrollback.
+ *    An environment block is per-process and not world-readable.
  *
- * Two leaks from one mistake. Argv is world-readable on Linux — any local user
- * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
- * the key was additionally written to stdout, so it landed in CI logs, terminal
- * scrollback, and anything scraping driver output.
- *
- * Secrets go through the environment instead, which is per-process and not
- * world-readable, and the command is built as an ARGV ARRAY for `execFile`
- * rather than a joined string for a shell, so a path with a space or a quote
- * cannot reshape the command.
+ * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
+ *    for a shell, so a screenshot path containing a space or a quote cannot
+ *    reshape the command.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.API_PROVIDER = exports.API_KEY_ENV = void 0;
+exports.API_PROVIDER = exports.RESAMPLE_LEVEL_ENV = exports.API_KEY_ENV = void 0;
 exports.buildSolveArgs = buildSolveArgs;
 exports.solveEnv = solveEnv;
 exports.redactCommand = redactCommand;
 /** Env var the CLI reads the bearer token from. */
 exports.API_KEY_ENV = 'CAPTCHA_KRAKEN_API_KEY';
-/** Historical positional placeholder. The CLI still accepts the slot. */
+/** Env var carrying the re-ask level for a board the vendor already refused. */
+exports.RESAMPLE_LEVEL_ENV = 'CAPTCHA_RESAMPLE_LEVEL';
+/** Positional placeholder the CLI still accepts in this slot. */
 exports.API_PROVIDER = 'captchaKrakenApi';
 /**
  * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
  * supplied by `solveEnv` instead.
  */
 function buildSolveArgs(invocation) {
-    const { imagePath, model, puzzleSource, retryMode, textMode } = invocation;
+    const { imagePath, model, puzzleSource, retryMode, textMode, expert } = invocation;
     const args = [
         '-m',
         'captchakraken.cli',
@@ -46,13 +44,27 @@ function buildSolveArgs(invocation) {
         args.push(`--retry-mode=${retryMode}`);
     if (textMode)
         args.push('--text-mode');
+    // Only when set. An absent flag is what lets the Python side route by prompt
+    // family, and passing `--expert=` would be an empty choice rather than none.
+    if (expert)
+        args.push(`--expert=${expert}`);
     return args;
 }
 /** Base env plus the credential, when there is one. */
-function solveEnv(base, apiKey) {
-    if (!apiKey)
-        return base;
-    return { ...base, [exports.API_KEY_ENV]: apiKey };
+function solveEnv(base, apiKey, resampleLevel) {
+    const out = apiKey ? { ...base, [exports.API_KEY_ENV]: apiKey } : { ...base };
+    // How many times THIS board has already been read and refused. The CLI is a
+    // fresh process per round, so it cannot know; and without it a re-ask is the
+    // same greedy arithmetic on the same pixels and returns the same answer,
+    // which is the whole of the "same answer 3 times running" failure.
+    //
+    // The LEVEL travels, not the temperature: the schedule lives once, in
+    // `planner.RESAMPLE_TEMPERATURES`, so the two ports cannot drift apart on a
+    // number Tier 3 would then average.
+    if (resampleLevel && resampleLevel > 0) {
+        out[exports.RESAMPLE_LEVEL_ENV] = String(resampleLevel);
+    }
+    return out;
 }
 /**
  * A log line for a solve invocation, with any credential removed.

package/dist/errors.d.ts

@@ -14,7 +14,7 @@
  * message drift, and the Python one is also what a direct CLI user sees.
  */
 /** The machine-readable half. Mirrors the gateway's `GatewayErrorCode`. */
-export type CaptchaKrakenErrorCode = 'missing_api_key' | 'invalid_api_key' | 'account_suspended' | 'insufficient_credits' | 'rate_limited' | 'solve_abandoned' | 'unrecognized_prompt' | 'invalid_request' | 'request_too_large' | 'upstream_unavailable' | (string & {});
+export type CaptchaKrakenErrorCode = 'missing_api_key' | 'invalid_api_key' | 'account_suspended' | 'insufficient_credits' | 'rate_limited' | 'solve_abandoned' | 'unrecognized_prompt' | 'invalid_request' | 'request_too_large' | 'upstream_unavailable' | 'model_not_licensed' | 'model_not_serving' | (string & {});
 export declare class CaptchaKrakenAPIError extends Error {
     readonly status: number | undefined;
     readonly code: CaptchaKrakenErrorCode | undefined;

package/dist/humanize.d.ts

@@ -0,0 +1,377 @@
+/**
+ * How the driver MOVES. One pluggable object per input device.
+ *
+ * The TypeScript side of `python/src/captchakraken/humanize.py`; the two are one
+ * design in two languages, and `the training repo's humanizer parity tests` in
+ * the training repo pins that the mode names and the pause vocabulary have
+ * not drifted.
+ *
+ * Humanisation used to be wired straight into `solver.ts`: every gesture was a
+ * `page.mouse.*` call with a Bezier trajectory in front of it and a `Math.
+ * random()` sleep behind it, and there was no way to ask for anything else. That
+ * is wrong in three directions at once —
+ *
+ *   - a caller driving a MOBILE page has no cursor. Dispatching mousemove at a
+ *     touch-only widget is not weak humanisation, it is the wrong event type:
+ *     the page's touch handlers never fire, and a vendor that scores pointer
+ *     telemetry sees a desktop mouse on a phone.
+ *   - a caller who has their OWN humanisation (a hardware pointer, a proxied
+ *     device farm, a model of their own users) was composing two of them. That
+ *     is not hypothetical — camoufox's `humanize` juggler re-humanises every
+ *     `mouse.move()` it is handed, and running both measured 82.1s against
+ *     13.4s on one a GeeTest v4 slider solve, because each of the 60 trajectory
+ *     points became its own humanised sub-trajectory.
+ *   - a caller on their own infrastructure, against their own fixtures, is
+ *     paying for texture nobody is measuring.
+ *
+ * So the vocabulary of gestures is an INTERFACE and the humanisation is an
+ * implementation of it. The solver says "tap here", "drag this there", "type
+ * that"; a `Humanizer` decides what events that is and how long it takes.
+ *
+ * Four modes, selected by `CaptchaKrakenConfig.humanization`:
+ *
+ *     'mouse'   MouseHumanizer   — the default, and byte-for-byte what the
+ *                                  driver did before this module existed.
+ *     'mobile'  MobileHumanizer  — touch events, finger kinematics. Dispatches
+ *                                  through a `TouchBackend`, so it drives either
+ *                                  a Chromium-family page (CDP) or an
+ *                                  Appium/WebdriverIO driver on a real device.
+ *     'none'    NullHumanizer    — the shortest legal path to the same DOM
+ *                                  effect.
+ *     custom    anything satisfying `Humanizer`, passed as
+ *                                  `CaptchaKrakenConfig.humanizer`.
+ *
+ * THE POINTER POSITION LIVES HERE, not in the solver. A humanizer that
+ * dispatches no motion at all (mobile, between taps) still has to answer "where
+ * is the pointer", because that is what the next gesture starts from and what
+ * `SolveResult.finalMousePosition` reports.
+ */
+import type { Page, PlaywrightElementHandle } from './playwright-types.js';
+export type Point = [number, number];
+/**
+ * Every inter-gesture wait the driver takes, named.
+ *
+ * A vocabulary rather than a number at each call site, because the whole point
+ * of the mode switch is that these differ per device — a finger dwells on a tap
+ * about four times as long as a mouse button is held, and neither number means
+ * anything to the caller who turned humanisation off. Each mode supplies its own
+ * table below; an unknown name yields no wait rather than throwing, so adding a
+ * pause site cannot break a custom humanizer written against an older release.
+ *
+ *   tap      inside a click/tap, between press and release
+ *   between  between two taps of one batch (grid tiles)
+ *   grab     after pressing, before a drag starts moving
+ *   drop     after a drag arrives, before releasing
+ *   probe    between the slider's measurement nudges
+ *   settle   before releasing a slider — the release IS the submit, and some
+ *            vendors sample the final milliseconds of the gesture
+ *   key      between two typed characters
+ */
+export type PauseKind = 'tap' | 'between' | 'grab' | 'drop' | 'probe' | 'settle' | 'key';
+export declare const PAUSE_KINDS: readonly PauseKind[];
+/**
+ * The gesture vocabulary the solver drives. Implement this to supply your own
+ * humanisation; only `move`, `press`, `release`, `typeText` and `pause` are
+ * required, and `BaseHumanizer` composes `click`/`drag` from them.
+ */
+export interface Humanizer {
+    /** Mode name, for logs. */
+    readonly name: string;
+    /**
+     * Whether this device has a cursor that can rest somewhere without touching.
+     * False switches off every hover-for-realism behaviour — the reCAPTCHA tile
+     * hover and the idle drift during inference — because on a touchscreen those
+     * are not weak mimicry, they are impossible.
+     */
+    readonly hovers: boolean;
+    /** Where the pointer is now. */
+    at: Point;
+    /** Called once at the top of each `solve()`. Drop per-page caches. */
+    reset(page: Page): Promise<void>;
+    move(page: Page, to: Point): Promise<void>;
+    press(page: Page): Promise<void>;
+    release(page: Page): Promise<void>;
+    click(page: Page, to: Point): Promise<void>;
+    drag(page: Page, src: Point, dst: Point): Promise<void>;
+    typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
+    pause(kind: PauseKind): Promise<void>;
+}
+type PauseTable = Record<string, [number, number]>;
+export declare abstract class BaseHumanizer implements Humanizer {
+    abstract readonly name: string;
+    abstract readonly hovers: boolean;
+    protected abstract readonly pauses: PauseTable;
+    at: Point;
+    constructor(start?: Point);
+    reset(_page: Page): Promise<void>;
+    abstract move(page: Page, to: Point): Promise<void>;
+    abstract press(page: Page): Promise<void>;
+    abstract release(page: Page): Promise<void>;
+    abstract typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
+    protected pauseMs(kind: PauseKind): number;
+    pause(kind: PauseKind): Promise<void>;
+    click(page: Page, to: Point): Promise<void>;
+    drag(page: Page, src: Point, dst: Point): Promise<void>;
+}
+/**
+ * A hand on a mouse. Bezier arcs, Fitts's-law durations, overshoot.
+ *
+ * Everything in here was `solver.performSmoothMove` / `tracePath` before this
+ * module existed, and is unchanged: the constants were measured and a refactor
+ * is not the place to revisit them.
+ */
+export declare class MouseHumanizer extends BaseHumanizer {
+    readonly name = "mouse";
+    readonly hovers = true;
+    /** Inclusive ranges, in ms. See PauseKind. */
+    protected readonly pauses: PauseTable;
+    private frequency;
+    constructor(start?: Point, frequency?: number);
+    move(page: Page, to: Point): Promise<void>;
+    press(page: Page): Promise<void>;
+    release(page: Page): Promise<void>;
+    typeText(page: Page, _field: PlaywrightElementHandle, text: string): Promise<boolean>;
+    private trace;
+}
+/** `[x, y, dtMs]` — dt is the wait BEFORE that sample. */
+export type TouchSample = [number, number, number];
+/**
+ * Where touch events actually go.
+ *
+ * Three methods rather than one per sample, because the two backends want
+ * opposite things: CDP dispatches one event per call and we pace it locally,
+ * while a W3C/Appium driver takes a whole timed action chain in one round trip
+ * and paces it on the device. Handing `move` the entire leg lets each do what it
+ * is good at — and on a real device, pacing over the wire is not pacing at all.
+ */
+export interface TouchBackend {
+    readonly name: string;
+    down(x: number, y: number): Promise<void>;
+    move(path: TouchSample[]): Promise<void>;
+    up(x: number, y: number): Promise<void>;
+}
+/**
+ * `Input.dispatchTouchEvent` over a CDP session on a Playwright page.
+ *
+ * Chromium-family only, and that is checked at construction rather than
+ * discovered per gesture: WebKit and Firefox (camoufox included) expose no touch
+ * dispatch through Playwright at all, so the alternatives there are to fail
+ * loudly or to quietly emit MOUSE events at a touch-only widget. The second is
+ * worse than not running — the page's touch handlers never fire, the solve fails
+ * for a reason nothing reports, and the report reads as a model that cannot
+ * solve mobile puzzles.
+ *
+ * The context must also have been created with `hasTouch: true`, or the page
+ * advertises no touch support to feature detection and a mobile widget renders
+ * its desktop branch.
+ */
+export declare class CdpTouchBackend implements TouchBackend {
+    readonly name = "cdp";
+    private session;
+    private constructor();
+    static open(page: Page): Promise<CdpTouchBackend>;
+    private send;
+    down(x: number, y: number): Promise<void>;
+    move(path: TouchSample[]): Promise<void>;
+    up(_x: number, _y: number): Promise<void>;
+}
+/** CSS-pixel → device-pixel transform for a real handset. See AppiumTouchBackend. */
+export interface TouchTransform {
+    scale?: number;
+    origin?: Point;
+}
+/**
+ * W3C pointer actions with `pointerType: 'touch'`, for Appium and WebdriverIO.
+ *
+ * Batches a whole leg into ONE action chain with per-sample durations, so the
+ * kinematics are reproduced BY THE DEVICE rather than by a JS loop round-tripping
+ * over the wire — over which a 90Hz path is not 90Hz at all.
+ *
+ * Press and release are separate `performActions()` calls on purpose. W3C input
+ * state is per SESSION, so a pointer put down in one chain stays down across
+ * later chains until it is lifted; that is what lets the puzzle-slider driver
+ * press, screenshot, steer, screenshot and only then release. (It is also why
+ * the spec has a "release actions" endpoint at all.)
+ *
+ * COORDINATES. Everything upstream of here is CSS pixels in the page's viewport,
+ * because that is what `boundingBox()` returns. A real device wants screen
+ * pixels, and the two differ by the device pixel ratio and by whatever chrome
+ * sits above the webview. Neither is guessable from here, so both are options:
+ *
+ *     new AppiumTouchBackend(driver, { scale: 3, origin: [0, 132] })
+ *
+ * `scale` is usually `window.devicePixelRatio`; `origin` is the top-left of the
+ * webview in screen coordinates. Defaults are the identity transform, which is
+ * correct for browser mobile emulation and for any caller who has already mapped
+ * the coordinates themselves.
+ */
+export declare class AppiumTouchBackend implements TouchBackend {
+    readonly name = "appium";
+    private driver;
+    private scale;
+    private origin;
+    /**
+     * UNSET is not the same fact as an explicit 1. The first is a caller who has
+     * not thought about the transform; the second is one who has, and says the
+     * coordinates are already mapped. Only the first is checked.
+     */
+    private scaleGiven;
+    private page;
+    private checked;
+    constructor(driver: any, transform?: TouchTransform, page?: Page);
+    /**
+     * Refuse an unset scale on a session that reports it is not 1.
+     *
+     * A wrong transform fails SILENTLY on both sides of the wire: the chain is
+     * valid W3C, the device performs it, and the finger lands somewhere else. The
+     * solve then fails looking exactly like a model that cannot read the puzzle.
+     *
+     * Read once, not per gesture — it is a round trip into the page and a solve
+     * makes hundreds of these. An unreadable ratio is absent evidence, not
+     * evidence of a mismatch, so it falls through to the identity. `origin`
+     * cannot be measured from here at all, so it is named in the refusal rather
+     * than guessed at.
+     */
+    private checkScale;
+    private map;
+    /**
+     * One W3C action chain on a single touch pointer.
+     *
+     * Sent as the raw protocol payload rather than through a client's action
+     * builder, so this imports nothing and works against any client that speaks
+     * WebDriver — WebdriverIO (`performActions`), selenium-webdriver, or a thin
+     * HTTP wrapper of someone's own.
+     */
+    private perform;
+    down(x: number, y: number): Promise<void>;
+    move(path: TouchSample[]): Promise<void>;
+    up(_x: number, _y: number): Promise<void>;
+}
+/**
+ * Playwright's `page.touchscreen.tap()` — taps only, no travel.
+ *
+ * The fallback for a browser with touch support but no CDP (WebKit). A tap still
+ * lands correctly; a DRAG cannot be expressed at all, so it throws rather than
+ * approximating one with a mouse, for the reason in `CdpTouchBackend`.
+ */
+export declare class TouchscreenTouchBackend implements TouchBackend {
+    readonly name = "touchscreen";
+    private page;
+    private pending;
+    constructor(page: Page);
+    down(x: number, y: number): Promise<void>;
+    move(_path: TouchSample[]): Promise<void>;
+    up(x: number, y: number): Promise<void>;
+}
+/**
+ * Pick a backend. An explicit `driver` always wins.
+ *
+ * `driver` is what a caller passes when the thing under automation is not the
+ * thing being touched — an Appium session driving a real handset while the page
+ * object is a webview bridge over it.
+ */
+export declare function touchBackendFor(page: Page, driver?: any, transform?: TouchTransform): Promise<TouchBackend>;
+/**
+ * A finger on glass.
+ *
+ * What differs from `MouseHumanizer`, and none of it is cosmetic:
+ *
+ *   - **A move that is not touching dispatches nothing.** There is no hover on a
+ *     touchscreen. The position is still RECORDED, because the next gesture
+ *     starts from it, but no event is emitted — emitting one would be the
+ *     desktop tell this mode exists to remove.
+ *   - **Taps carry a contact wobble.** A finger held on glass for 90ms does not
+ *     report one unchanging coordinate; the centroid of the contact patch rolls
+ *     a pixel or two under pressure. A tap with zero movement between touchstart
+ *     and touchend is a synthetic tap.
+ *   - **Touch kinematics**, via `generate_swipe` — see its docstring for why that
+ *     is a different model rather than the mouse one retuned.
+ *   - **Longer, more variable pauses.** Every measured touch interaction is
+ *     slower than its mouse equivalent, and a phone's are more variable because
+ *     the hand holding the device is also moving.
+ */
+export declare class MobileHumanizer extends BaseHumanizer {
+    readonly name = "mobile";
+    readonly hovers = false;
+    protected readonly pauses: PauseTable;
+    private backend;
+    private driver;
+    private transform;
+    private frequency;
+    private down;
+    constructor(start?: Point, options?: {
+        backend?: TouchBackend;
+        driver?: any;
+        transform?: TouchTransform;
+        frequency?: number;
+    });
+    reset(page: Page): Promise<void>;
+    private touch;
+    move(page: Page, to: Point): Promise<void>;
+    press(page: Page): Promise<void>;
+    release(page: Page): Promise<void>;
+    /** Tap. The wobble is the point — see the class docstring. */
+    click(page: Page, to: Point): Promise<void>;
+    /**
+     * Into the field, at soft-keyboard pace.
+     *
+     * The mouse path clears with Control+A. There is no Control on a phone
+     * keyboard, so the box is cleared through the element instead — which also
+     * works on an Appium element, where `page.keyboard` does not exist.
+     */
+    typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
+}
+/**
+ * No humanisation: the shortest legal path to the same DOM effect.
+ *
+ * One mousemove per gesture instead of sixty, no dwell, no jitter, and text goes
+ * in with a single `fill()`. Roughly an order of magnitude faster on a slider
+ * puzzle, and it will be detected by anything that scores pointer telemetry —
+ * which is the whole trade, stated plainly. For fixtures, for self-hosted
+ * targets, and for callers whose stack humanises somewhere else.
+ *
+ * Still moves the mouse and still presses and releases: the events are what make
+ * the widget respond at all, and a click dispatched with no preceding move fails
+ * on the vendors that require a hover state first.
+ */
+export declare class NullHumanizer extends BaseHumanizer {
+    readonly name = "none";
+    readonly hovers = false;
+    protected readonly pauses: PauseTable;
+    move(page: Page, to: Point): Promise<void>;
+    press(page: Page): Promise<void>;
+    release(page: Page): Promise<void>;
+    typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
+}
+export type HumanizationMode = 'mouse' | 'mobile' | 'none';
+export declare const MODES: readonly HumanizationMode[];
+/** The subset of `CaptchaKrakenConfig` this module reads. */
+export interface HumanizerOptions {
+    humanization?: HumanizationMode;
+    humanizer?: Humanizer;
+    touchDriver?: any;
+    touchTransform?: TouchTransform;
+    startingMousePosition?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * The humanizer one solver will use, from its config.
+ *
+ * Precedence, and the reasoning for it:
+ *
+ *   1. `config.humanizer` — a caller who handed us an OBJECT has already
+ *      decided; there is nothing left to select.
+ *   2. `config.humanization` — an explicit mode set in code.
+ *   3. `CAPTCHA_HUMANIZATION` — for a caller who cannot edit the code.
+ *   4. 'mouse'.
+ *
+ * Note that the env var loses to code, which is the opposite of this package's
+ * model-identity settings. Deliberate: which mode is right is a property of the
+ * PAGE the caller is driving, and an env var flipping a desktop solve to touch
+ * dispatch would break every one of them silently. Pinning a model is a
+ * deployment decision; picking an input device is not.
+ */
+export declare function resolveHumanizer(config?: HumanizerOptions): Humanizer;
+export {};