captchakraken 2.6.1 → 2.9.0

package/dist/timing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where one solve's wall-clock went, by phase.
+ *
+ * The TypeScript half of `python/src/captchakraken/timing.py`; the two are one
+ * implementation in two languages and `test_timing_parity.py` pins that they
+ * name the same phases. That parity is the point: without it the ports can only
+ * be compared on their totals, and "the JS port is four seconds slower" is not
+ * a bug report — "the JS port spends four seconds starting a Python
+ * interpreter it did not need to start" is.
+ *
+ * Always on. It is a few map updates per phase against multi-second waits, and
+ * a budget you have to opt into is one nobody has when the slow solve happens.
+ * Only PRINTED under `CAPTCHA_TIMINGS=1`; always RETURNED on `SolveResult`.
+ */
+/**
+ * What a phase's time COUNTS AS, when asking how much of a solve was useful.
+ *
+ * Only two kinds of second are worth spending: one the model is thinking in,
+ * and one the pointer is travelling in (which has to look human, so it cannot
+ * be rushed). Everything else is the driver waiting on a clock, and every such
+ * wait is a candidate for deletion or for overlapping with something real.
+ */
+export declare const PRODUCTIVE: Set<string>;
+export declare function timingsEnabled(): boolean;
+export declare class PhaseBudget {
+    readonly totals: Map<string, number>;
+    readonly counts: Map<string, number>;
+    private readonly open;
+    private readonly t0;
+    /**
+     * Attribute `fn`'s wall-clock to `name`.
+     *
+     * Phases may nest (a burst contains its screenshots). Only the OUTERMOST of a
+     * given NAME accumulates, so re-entering one cannot double-count it — but a
+     * phase nested inside a differently-named one counts under both, deliberately:
+     * the cursor drifting over the widget WHILE the model generates is genuinely
+     * both `mouse` and `inference`, and hiding either would misreport what the
+     * solve was doing. The totals are therefore an attribution, not a partition,
+     * and can exceed the elapsed time.
+     */
+    phase<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /** Record a measured span directly, for blocks that would need re-indenting. */
+    add(name: string, ms: number): void;
+    elapsedMs(): number;
+    /** Plain object for `SolveResult.phases`, with the solve total folded in. */
+    toObject(): Record<string, number>;
+    report(): string;
+}

package/dist/timing.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Where one solve's wall-clock went, by phase.
+ *
+ * The TypeScript half of `python/src/captchakraken/timing.py`; the two are one
+ * implementation in two languages and `test_timing_parity.py` pins that they
+ * name the same phases. That parity is the point: without it the ports can only
+ * be compared on their totals, and "the JS port is four seconds slower" is not
+ * a bug report — "the JS port spends four seconds starting a Python
+ * interpreter it did not need to start" is.
+ *
+ * Always on. It is a few map updates per phase against multi-second waits, and
+ * a budget you have to opt into is one nobody has when the slow solve happens.
+ * Only PRINTED under `CAPTCHA_TIMINGS=1`; always RETURNED on `SolveResult`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhaseBudget = exports.PRODUCTIVE = void 0;
+exports.timingsEnabled = timingsEnabled;
+/**
+ * What a phase's time COUNTS AS, when asking how much of a solve was useful.
+ *
+ * Only two kinds of second are worth spending: one the model is thinking in,
+ * and one the pointer is travelling in (which has to look human, so it cannot
+ * be rushed). Everything else is the driver waiting on a clock, and every such
+ * wait is a candidate for deletion or for overlapping with something real.
+ */
+exports.PRODUCTIVE = new Set(['inference', 'mouse']);
+function timingsEnabled() {
+    return process.env.CAPTCHA_TIMINGS === '1';
+}
+class PhaseBudget {
+    constructor() {
+        this.totals = new Map();
+        this.counts = new Map();
+        this.open = [];
+        this.t0 = Date.now();
+    }
+    /**
+     * Attribute `fn`'s wall-clock to `name`.
+     *
+     * Phases may nest (a burst contains its screenshots). Only the OUTERMOST of a
+     * given NAME accumulates, so re-entering one cannot double-count it — but a
+     * phase nested inside a differently-named one counts under both, deliberately:
+     * the cursor drifting over the widget WHILE the model generates is genuinely
+     * both `mouse` and `inference`, and hiding either would misreport what the
+     * solve was doing. The totals are therefore an attribution, not a partition,
+     * and can exceed the elapsed time.
+     */
+    async phase(name, fn) {
+        if (this.open.includes(name))
+            return fn();
+        this.open.push(name);
+        const t0 = Date.now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.open.splice(this.open.indexOf(name), 1);
+            this.add(name, Date.now() - t0);
+        }
+    }
+    /** Record a measured span directly, for blocks that would need re-indenting. */
+    add(name, ms) {
+        this.totals.set(name, (this.totals.get(name) ?? 0) + ms);
+        this.counts.set(name, (this.counts.get(name) ?? 0) + 1);
+    }
+    elapsedMs() {
+        return Date.now() - this.t0;
+    }
+    /** Plain object for `SolveResult.phases`, with the solve total folded in. */
+    toObject() {
+        const out = {};
+        for (const [k, v] of this.totals)
+            out[k] = v;
+        out.total = this.elapsedMs();
+        return out;
+    }
+    report() {
+        const total = this.elapsedMs();
+        let useful = 0;
+        for (const [k, v] of this.totals)
+            if (exports.PRODUCTIVE.has(k))
+                useful += v;
+        const rows = [...this.totals.entries()].sort((a, b) => b[1] - a[1]);
+        const lines = [
+            `[BUDGET] solve ${(total / 1000).toFixed(1)}s — ` +
+                `${(useful / 1000).toFixed(1)}s useful (${total ? Math.round((100 * useful) / total) : 0}%), ` +
+                `${((total - useful) / 1000).toFixed(1)}s waiting`,
+        ];
+        for (const [name, ms] of rows) {
+            const tag = exports.PRODUCTIVE.has(name) ? '*' : ' ';
+            lines.push(`[BUDGET] ${tag} ${name.padEnd(22)} ${(ms / 1000).toFixed(2).padStart(6)}s  x${this.counts.get(name)}`);
+        }
+        let attributed = 0;
+        for (const v of this.totals.values())
+            attributed += v;
+        if (total - attributed > 50) {
+            lines.push(`[BUDGET]   ${'(unattributed)'.padEnd(22)} ${((total - attributed) / 1000).toFixed(2).padStart(6)}s`);
+        }
+        return lines.join('\n');
+    }
+}
+exports.PhaseBudget = PhaseBudget;

package/dist/trajectory.d.ts

@@ -12,9 +12,13 @@
  *   - a small overshoot-and-correct on longer moves, which is the single most
  *     recognisable human tell and the one a linear interpolation never produces
  *
+ * `generate_swipe` is the SAME contract for a FINGER, and it is a different
+ * model rather than the mouse model with different constants — see its
+ * docstring.
+ *
  * Camoufox's own `humanize` is a DIFFERENT, browser-level mechanism that
  * re-humanises every `mouse.move()` it is handed. Running both composes them —
- * measured 82.1s vs 13.4s on one geetest_v4_slide solve, because each of the 60
+ * measured 82.1s vs 13.4s on one a GeeTest v4 slider solve, because each of the 60
  * points below became its own humanised sub-trajectory. Drive with humanize off.
  */
 export type Point = [number, number];
@@ -29,3 +33,26 @@ export type Point = [number, number];
  * detectable.
  */
 export declare function generate_trajectory(target_start: readonly number[], target_end: readonly number[], frequency?: number, frequencyRandomizer?: number): [Point[], number[]];
+/**
+ * A FINGER travelling from `target_start` to `target_end`, same contract as
+ * `generate_trajectory`: `[points, timings]`, timings cumulative from 0, last
+ * point exactly `target_end`.
+ *
+ * A separate model rather than `generate_trajectory` with other constants,
+ * because the three things that make the mouse output human are each WRONG
+ * here:
+ *
+ *   - **No overshoot-and-correct.** That tell is a hand arriving past a target
+ *     it cannot see under the cursor. A finger occludes its own target and
+ *     commits; the correction, when there is one, is a second gesture.
+ *   - **A different velocity profile.** `easeTouch`, not `easeInOut` — above.
+ *   - **Different jitter.** The mouse model adds white noise scaled by speed (a
+ *     hand tracking a path imprecisely). A digitizer instead reports a wandering
+ *     centroid, which is low-frequency and roughly speed INDEPENDENT, so this is
+ *     a smoothed random walk.
+ *
+ * `frequency` defaults to 90: digitizers sample at 120Hz+, but touchmove is
+ * coalesced to the compositor, so more samples than this buys nothing and costs
+ * a dispatch round-trip each.
+ */
+export declare function generate_swipe(target_start: readonly number[], target_end: readonly number[], frequency?: number, frequencyRandomizer?: number): [Point[], number[]];

package/dist/trajectory.js

@@ -13,13 +13,18 @@
  *   - a small overshoot-and-correct on longer moves, which is the single most
  *     recognisable human tell and the one a linear interpolation never produces
  *
+ * `generate_swipe` is the SAME contract for a FINGER, and it is a different
+ * model rather than the mouse model with different constants — see its
+ * docstring.
+ *
  * Camoufox's own `humanize` is a DIFFERENT, browser-level mechanism that
  * re-humanises every `mouse.move()` it is handed. Running both composes them —
- * measured 82.1s vs 13.4s on one geetest_v4_slide solve, because each of the 60
+ * measured 82.1s vs 13.4s on one a GeeTest v4 slider solve, because each of the 60
  * points below became its own humanised sub-trajectory. Drive with humanize off.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generate_trajectory = generate_trajectory;
+exports.generate_swipe = generate_swipe;
 // Fitts's law: MT = a + b * log2(distance / width + 1). The constants are the
 // usual empirical range for a mouse; `WIDTH` stands in for target precision.
 const FITTS_A_MS = 90.0;
@@ -160,3 +165,102 @@ function generate_trajectory(target_start, target_end, frequency = 60, frequency
     points[points.length - 1] = end;
     return [points, timings];
 }
+// ── Touch ───────────────────────────────────────────────────────────────────
+//
+// Fitts's law holds for direct touch too, but with a slower intercept and a much
+// wider effective target: a fingertip contact patch is ~9mm across, which is the
+// 44pt / 48dp minimum both platform guidelines are built around. So the same
+// distance takes longer AND is aimed less precisely than with a mouse.
+const TOUCH_FITTS_A_MS = 160.0;
+const TOUCH_FITTS_B_MS = 135.0;
+const TOUCH_WIDTH_PX = 44.0;
+// How flick-like the launch is. 0 would be the mouse's symmetric bell; 1 would
+// be an instantaneous jump at t=0. See `easeTouch`.
+const TOUCH_LAUNCH = 0.7;
+// A finger drags across glass on a short wrist/thumb pivot, so it bows far less
+// than a hand moving a mouse across a desk.
+const TOUCH_BOW_CAP_PX = 40.0;
+// The reported contact point wanders, because it is the CENTROID of a soft patch
+// rolling under pressure rather than a rigid sensor. `TOUCH_WOBBLE_DECAY` is the
+// AR(1) coefficient that makes that wander low-frequency: white per-sample noise
+// would show up in a spectrum as nothing a finger produces.
+const TOUCH_WOBBLE_PX = 0.55;
+const TOUCH_WOBBLE_DECAY = 0.82;
+/**
+ * Asymmetric ease: a finger leaves fast and brakes late.
+ *
+ * A mouse hand is symmetric (`easeInOut` — accelerate, decelerate, equally). A
+ * finger is not: the launch is a flick off the contact point and the arrival is
+ * a brake. Blending the two rather than using a pure ease-out is what keeps the
+ * launch from being an instantaneous jump at t=0, which no digitizer would ever
+ * report.
+ */
+function easeTouch(t) {
+    return (1.0 - TOUCH_LAUNCH) * easeInOut(t) + TOUCH_LAUNCH * (1.0 - Math.pow(1.0 - t, 2.4));
+}
+/**
+ * A FINGER travelling from `target_start` to `target_end`, same contract as
+ * `generate_trajectory`: `[points, timings]`, timings cumulative from 0, last
+ * point exactly `target_end`.
+ *
+ * A separate model rather than `generate_trajectory` with other constants,
+ * because the three things that make the mouse output human are each WRONG
+ * here:
+ *
+ *   - **No overshoot-and-correct.** That tell is a hand arriving past a target
+ *     it cannot see under the cursor. A finger occludes its own target and
+ *     commits; the correction, when there is one, is a second gesture.
+ *   - **A different velocity profile.** `easeTouch`, not `easeInOut` — above.
+ *   - **Different jitter.** The mouse model adds white noise scaled by speed (a
+ *     hand tracking a path imprecisely). A digitizer instead reports a wandering
+ *     centroid, which is low-frequency and roughly speed INDEPENDENT, so this is
+ *     a smoothed random walk.
+ *
+ * `frequency` defaults to 90: digitizers sample at 120Hz+, but touchmove is
+ * coalesced to the compositor, so more samples than this buys nothing and costs
+ * a dispatch round-trip each.
+ */
+function generate_swipe(target_start, target_end, frequency = 90, frequencyRandomizer = 0.1) {
+    const start = [Number(target_start[0]), Number(target_start[1])];
+    const end = [Number(target_end[0]), Number(target_end[1])];
+    const dx = end[0] - start[0];
+    const dy = end[1] - start[1];
+    const distance = Math.hypot(dx, dy);
+    if (distance < 1e-6)
+        return [[end], [0.0]];
+    let durationMs = TOUCH_FITTS_A_MS + TOUCH_FITTS_B_MS * Math.log2(distance / TOUCH_WIDTH_PX + 1.0);
+    durationMs *= uniform(0.85, 1.2);
+    const steps = Math.max(2, Math.round((durationMs / 1000.0) * Math.max(1, frequency)));
+    let c1;
+    let c2;
+    if (distance < SHORT_MOVE_PX) {
+        c1 = start;
+        c2 = end;
+    }
+    else {
+        [c1, c2] = controlPoints(start, end, distance);
+        // Pull the mouse model's bow in: `controlPoints` is shared, and its arc is
+        // sized for a hand crossing a desk.
+        const shrink = Math.min(1.0, TOUCH_BOW_CAP_PX / Math.max(TOUCH_BOW_CAP_PX, distance * 0.16));
+        c1 = [start[0] + (c1[0] - start[0]) * shrink, start[1] + (c1[1] - start[1]) * shrink];
+        c2 = [start[0] + (c2[0] - start[0]) * shrink, start[1] + (c2[1] - start[1]) * shrink];
+    }
+    const points = [];
+    const timings = [];
+    let elapsed = 0.0;
+    const perStep = durationMs / steps;
+    let wobX = 0.0;
+    let wobY = 0.0;
+    for (let i = 0; i <= steps; i++) {
+        const t = easeTouch(i / steps);
+        const [px, py] = cubicBezier(start, c1, c2, end, t);
+        wobX = wobX * TOUCH_WOBBLE_DECAY + gauss(0.0, TOUCH_WOBBLE_PX);
+        wobY = wobY * TOUCH_WOBBLE_DECAY + gauss(0.0, TOUCH_WOBBLE_PX);
+        points.push([px + wobX, py + wobY]);
+        timings.push(elapsed);
+        elapsed += perStep * uniform(1.0 - frequencyRandomizer, 1.0 + frequencyRandomizer);
+    }
+    // Land exactly where the caller asked, same reason as the mouse model.
+    points[points.length - 1] = end;
+    return [points, timings];
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Humanizer, HumanizationMode, TouchTransform } from './humanize.js';
 /**
  * Lifecycle event emitted by {@link CaptchaKrakenConfig.onStep}. One is fired
  * before any interaction (`stage: 'initial'`) and one after every executed
@@ -46,6 +47,65 @@ export interface SolveStepEvent {
     meta?: Record<string, any>;
 }
 export interface CaptchaKrakenConfig {
+    /**
+     * How the driver MOVES — a choice of input DEVICE, not a realism dial.
+     *
+     *  - `'mouse'`  (default) Bezier arcs, Fitts's-law durations, overshoot.
+     *  - `'mobile'` touch events with finger kinematics. On a touch-only widget
+     *               this is the difference between the page's handlers firing and
+     *               not; a mousemove there is the wrong event, not a weaker one.
+     *               Needs a Chromium-family page launched with `hasTouch: true`,
+     *               or an Appium/WebdriverIO driver in {@link touchDriver}.
+     *  - `'none'`   the shortest legal path to the same DOM effect. Much faster,
+     *               and detectable by anything scoring pointer telemetry — for
+     *               fixtures, self-hosted targets, and stacks that humanise
+     *               elsewhere.
+     *
+     * Unset falls back to `CAPTCHA_HUMANIZATION`, then `'mouse'`. Set
+     * {@link humanizer} instead to supply your own implementation.
+     *
+     * @example
+     * ```typescript
+     * const context = await browser.newContext({ ...devices['Pixel 7'], hasTouch: true });
+     * const solver = new CaptchaKrakenSolver({ humanization: 'mobile' });
+     * await solver.solve(await context.newPage());
+     * ```
+     */
+    humanization?: HumanizationMode;
+    /**
+     * Your own {@link Humanizer}. Overrides {@link humanization} entirely — the
+     * driver then makes no decisions about pointer motion at all.
+     *
+     * Use it when you already model your users' input (a hardware pointer, a
+     * device farm, a recorded trace), or when the browser humanises for you:
+     * camoufox's `humanize` juggler re-humanises every `mouse.move()` it is
+     * handed, and composing both measured 82.1s against 13.4s on one solve.
+     *
+     * @example
+     * ```typescript
+     * import { NullHumanizer, type Humanizer } from 'captchakraken';
+     *
+     * class MyPointer extends NullHumanizer implements Humanizer {
+     *   async move(page, to) { await myHardwareMouse.glideTo(to[0], to[1]); this.at = to; }
+     * }
+     * new CaptchaKrakenSolver({ humanizer: new MyPointer() });
+     * ```
+     */
+    humanizer?: Humanizer;
+    /**
+     * `humanization: 'mobile'` only. The thing that is actually TOUCHED, when it
+     * is not the page object — an Appium / WebdriverIO / Selenium driver on a real
+     * handset. Left unset, the mode dispatches CDP touch events at the page it
+     * was given, which is what browser mobile emulation wants.
+     */
+    touchDriver?: any;
+    /**
+     * `humanization: 'mobile'` only. CSS-pixel → device-pixel transform for
+     * {@link touchDriver}. `scale` is usually `window.devicePixelRatio`; `origin`
+     * is the top-left of the webview in screen coordinates. The default identity
+     * is right for emulation and for callers who map coordinates themselves.
+     */
+    touchTransform?: TouchTransform;
     /**
      * Optional observer fired at each intermediate solve stage. Receives a
      * baseline screenshot before any action and one after every executed action.
@@ -78,6 +138,23 @@ export interface CaptchaKrakenConfig {
      * with the vLLM server; see model-name.ts.
      */
     model?: string;
+    /**
+     * Force ONE expert of a ROUTED model — 'pixel' | 'grid' | 'video' | 'text'.
+     *
+     * A routed model (Abyss) is four LoRA adapters behind one endpoint, and the
+     * router is the prompt family each request is about to send — so leaving this
+     * unset already reaches the right expert. This is the override: serve one
+     * arm, drive only the puzzles it owns, which is what a per-arm benchmark
+     * needs and what a licence holder pinning a single expert wants.
+     *
+     * Refused against a model that serves a single adapter — every model
+     * published so far — rather than ignored, because a run that quietly measured
+     * the generalist while reporting an expert is a number nobody can catch.
+     *
+     * Mirrors the Python `PageSolverConfig.expert`; also settable as
+     * CAPTCHA_EXPERT, which this forwards to the CLI ahead of.
+     */
+    expert?: string;
     /**
      * Bearer token for the vLLM server (also picked up from VLLM_API_KEY env).
      */
@@ -330,6 +407,18 @@ export interface CaptchaKrakenConfig {
      */
     keyframeWaitTimeoutMs?: number;
     keyframeWaitPollMs?: number;
+    /**
+     * Hard ceiling on a burst that never repeats a screen. The burst normally
+     * ends when the cycle closes; this bounds a continuous animation, which never
+     * closes one. Default 12000ms.
+     */
+    videoBurstMaxMs?: number;
+    /**
+     * Record while the still screenshot is being read, so a cycling board is
+     * known before its answer is acted on. Default on. Off restores the older
+     * shape, which learned the same thing two rounds later.
+     */
+    speculativeBurstEnabled?: boolean;
     /**
      * Extra wall clock (ms) granted ONCE, the first time a solve escalates to a
      * recording. NOT a looser `overallSolveTimeoutMs`.
@@ -343,8 +432,8 @@ export interface CaptchaKrakenConfig {
      * timeout — which reads as a slow model rather than as a budget with no room
      * for what the solver had just decided to do.
      *
-     * Measured 2026-08-22, Tier 3 run 32596340560: hcaptcha_click_image_by_traits,
-     * hcaptcha_connect_path and hcaptcha_grid_3x3_property each failed this port
+     * Measured 2026-08-22, a full driver-gate run: an hCaptcha click-by-trait board,
+     * an hCaptcha connect-the-path board and an hCaptcha 3x3 property grid each failed this port
      * with "Captcha solve timed out after 45000ms (attempt 6/6)" at 49-59s, and
      * solve in 14-20s on the rounds the still path answers them.
      *
@@ -379,6 +468,18 @@ export interface CaptchaKrakenConfig {
      * Default: 8000
      */
     elementScreenshotTimeoutMs?: number;
+    /**
+     * How long an `onStep` observer's screenshot may take, ms (default 2000).
+     *
+     * Deliberately separate from `elementScreenshotTimeoutMs`, which is sized for
+     * the picture the MODEL reads. This one is a trace snapshot: it is taken with
+     * `animations: 'disabled'`, which makes Playwright wait for the element to
+     * stop moving first, and on a still-animating widget that ran to the full 8s
+     * on every step — 8.0s of a measured 12.0s solve. An observer must never cost
+     * more than the action it observes, and a missed frame in a trace costs
+     * nothing. Ignored entirely when no `onStep` is set.
+     */
+    stepScreenshotTimeoutMs?: number;
     /**
      * After a submit, hCaptcha may replace the challenge iframe for the next
      * round, detaching the handle we just detected ("element is not visible").
@@ -495,4 +596,14 @@ export interface SolveResult {
         cachedInputTokens: number;
         estimatedCost: number;
     };
+    /**
+     * Where this solve's wall-clock went, in milliseconds per phase — the same
+     * partition `CAPTCHA_TIMINGS=1` prints, handed to the caller instead of to
+     * stderr. Mirrors `SolveResult.phases` on the Python port.
+     *
+     * Returned rather than only logged because "the solve took 12s" is not
+     * actionable and "the settle monitor spent 4s of it" is, and a caller
+     * measuring a fleet cannot scrape another process's stderr.
+     */
+    phases?: Record<string, number>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captchakraken",
-  "version": "2.6.1",
+  "version": "2.9.0",
   "description": "Captcha solver for Playwright and Puppeteer. Finds the captcha, reads the puzzle with a fine-tuned Qwen3.5-9B vision model, and clicks, drags, slides or types through to a token — reCAPTCHA, hCaptcha, GeeTest, NetEase Yidun, Tencent, Lemin, Prosopo, Turnstile and distorted text. Hosted API or self-hosted.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,7 @@
   "scripts": {
     "prebuild": "node scripts/copy-python.mjs",
     "build": "tsc",
+    "demo": "tsx examples/demoSites.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "tsc -p tsconfig.test.json && node --test .test-build/*.test.js",
     "prepublishOnly": "npm run build",

package/python/README.md

@@ -21,6 +21,26 @@ nothing at all.
 > self-hosting guide, see 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).
+
 ## What it solves
 
 | Vendor | Puzzles |
@@ -107,6 +127,29 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 | `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken-Lora-v1.2` |
 | `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha-v12` |
 | `CAPTCHA_KRAKEN_AUTOSTART` | `0` disables local auto-start | `1` |
+| `CAPTCHA_HUMANIZATION` | How gestures are performed: `mouse`, `mobile` or `none` | `mouse` |
+
+**How it moves** is a choice of input device, not a realism dial. `mobile`
+dispatches real touch events with finger kinematics and never touches
+`page.mouse`; `none` goes straight to the DOM effect. Set it in code (which wins
+over the env var, because the right mode is a property of the page you are
+driving), and pass your own object to override ours entirely:
+
+```python
+from captchakraken import PageSolver
+from captchakraken.page_solver import PageSolverConfig
+
+PageSolver(config=PageSolverConfig(humanization="mobile"))
+PageSolver(config=PageSolverConfig(humanization="none"))
+PageSolver(config=PageSolverConfig(humanizer=my_own))
+
+# A real handset over Appium / Selenium — W3C touch pointer actions.
+PageSolver(config=PageSolverConfig(
+    humanization="mobile",
+    touch_driver=driver,
+    touch_transform={"scale": 3.0, "origin": (0, 132)},   # CSS px -> screen px
+))
+```
 
 ## License
 

package/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.6.1"
+version = "2.9.0"
 description = "Captcha-solving engine and CLI: OpenCV grid detection plus a fine-tuned Qwen3.5-9B vision model, for image grids, click and drag puzzles, sliders, distorted text and animated challenges. Hosted API or self-hosted on vLLM."
 readme = "README.md"
 requires-python = ">=3.10"

package/python/src/captchakraken/__init__.py

@@ -32,6 +32,27 @@ from .action_types import (
 from .image_processor import ImageProcessor
 from .overlay import add_overlays_to_image
 
+# The hosted API's refusal type. Outside the try below on purpose: `errors`
+# imports nothing but `typing`, and docs/hosted-api.md tells every caller to
+# branch on its `.code` — a recipe that has to work in both ports, and in a
+# minimal install that has no serving stack.
+from .errors import CaptchaKrakenAPIError
+
+# How gestures are PERFORMED — mouse, touch, or nothing. Deliberately outside
+# the try below: `humanize` imports only `trajectory`, so it has no dependency
+# floor at all, and a caller writing a custom Humanizer must be able to import
+# the base class without the serving stack installed.
+from .humanize import (
+    AppiumTouchBackend,
+    CdpTouchBackend,
+    Humanizer,
+    MobileHumanizer,
+    MouseHumanizer,
+    NullHumanizer,
+    TouchBackend,
+    TouchscreenTouchBackend,
+)
+
 # The planner (requests) and solver (torch/vllm/transformers) pull in the heavy
 # serving stack. Keep them optional so leaf modules — e.g. tool_calls.find_grid,
 # which needs only cv2 + numpy + pillow — can be imported in a minimal env (CI's
@@ -70,6 +91,20 @@ __all__ = [
     "TypeAction",
     "WaitAction",
     "add_overlays_to_image",
+    "CaptchaKrakenAPIError",
+    "Humanizer",
+    "MouseHumanizer",
+    "MobileHumanizer",
+    "NullHumanizer",
+    "TouchBackend",
+    "CdpTouchBackend",
+    "AppiumTouchBackend",
+    "TouchscreenTouchBackend",
 ]
 
-__version__ = "2.6.0"
+# KEEP IN STEP with python/pyproject.toml and js/package.json — the two ports
+# ship together (rule 1c) and this is the only one importable code can read.
+# It said 2.6.0 while the wheel on PyPI said 2.6.1, so anyone gating on the
+# runtime attribute saw a version that had not been current for weeks.
+# tests/test_public_contract.py compares all three.
+__version__ = "2.9.0"