captchakraken 2.6.0 → 2.8.0

package/dist/index.d.ts

@@ -104,3 +104,36 @@ export type { Page, PlaywrightPage, PlaywrightFrame, PlaywrightElementHandle } f
  */
 export { watchPage } from './watcher';
 export type { CaptchaWatcher, WatchOptions, WatchableSolver } from './watcher';
+/**
+ * Humanisation: how the driver moves. `humanization: 'mouse' | 'mobile' |
+ * 'none'` picks a built-in; `humanizer` takes one of your own.
+ *
+ * `MobileHumanizer` emits real touch events with finger kinematics, through a
+ * `TouchBackend` — CDP against a Chromium-family page, or W3C pointer actions
+ * against an Appium / WebdriverIO driver on a real handset.
+ *
+ * @example Mobile emulation in the browser
+ * ```typescript
+ * import { chromium, devices } from 'playwright';
+ * import { CaptchaKrakenSolver } from 'captchakraken';
+ *
+ * const browser = await chromium.launch();
+ * const context = await browser.newContext({ ...devices['Pixel 7'], hasTouch: true });
+ * const page = await context.newPage();
+ * await page.goto('https://example.com/signup');
+ *
+ * await new CaptchaKrakenSolver({ humanization: 'mobile' }).solve(page);
+ * ```
+ *
+ * @example A real device over Appium
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver({
+ *   humanization: 'mobile',
+ *   touchDriver: driver,                                  // the WebdriverIO browser
+ *   touchTransform: { scale: 3, origin: [0, 132] },       // CSS px -> screen px
+ * });
+ * await solver.solve(page);
+ * ```
+ */
+export { MouseHumanizer, MobileHumanizer, NullHumanizer, BaseHumanizer, resolveHumanizer, touchBackendFor, CdpTouchBackend, AppiumTouchBackend, TouchscreenTouchBackend, PAUSE_KINDS, MODES as HUMANIZATION_MODES, } from './humanize';
+export type { Humanizer, HumanizationMode, HumanizerOptions, TouchBackend, TouchSample, TouchTransform, PauseKind, } from './humanize';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchPage = exports.fromPuppeteer = exports.CaptchaKrakenAPIError = exports.resolveLoraName = exports.CaptchaKrakenSolver = void 0;
+exports.HUMANIZATION_MODES = exports.PAUSE_KINDS = exports.TouchscreenTouchBackend = exports.AppiumTouchBackend = exports.CdpTouchBackend = exports.touchBackendFor = exports.resolveHumanizer = exports.BaseHumanizer = exports.NullHumanizer = exports.MobileHumanizer = exports.MouseHumanizer = exports.watchPage = exports.fromPuppeteer = exports.CaptchaKrakenAPIError = exports.resolveLoraName = exports.CaptchaKrakenSolver = void 0;
 __exportStar(require("./types"), exports);
 var solver_1 = require("./solver");
 Object.defineProperty(exports, "CaptchaKrakenSolver", { enumerable: true, get: function () { return solver_1.CaptchaKrakenSolver; } });
@@ -92,3 +92,46 @@ Object.defineProperty(exports, "fromPuppeteer", { enumerable: true, get: functio
  */
 var watcher_1 = require("./watcher");
 Object.defineProperty(exports, "watchPage", { enumerable: true, get: function () { return watcher_1.watchPage; } });
+/**
+ * Humanisation: how the driver moves. `humanization: 'mouse' | 'mobile' |
+ * 'none'` picks a built-in; `humanizer` takes one of your own.
+ *
+ * `MobileHumanizer` emits real touch events with finger kinematics, through a
+ * `TouchBackend` — CDP against a Chromium-family page, or W3C pointer actions
+ * against an Appium / WebdriverIO driver on a real handset.
+ *
+ * @example Mobile emulation in the browser
+ * ```typescript
+ * import { chromium, devices } from 'playwright';
+ * import { CaptchaKrakenSolver } from 'captchakraken';
+ *
+ * const browser = await chromium.launch();
+ * const context = await browser.newContext({ ...devices['Pixel 7'], hasTouch: true });
+ * const page = await context.newPage();
+ * await page.goto('https://example.com/signup');
+ *
+ * await new CaptchaKrakenSolver({ humanization: 'mobile' }).solve(page);
+ * ```
+ *
+ * @example A real device over Appium
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver({
+ *   humanization: 'mobile',
+ *   touchDriver: driver,                                  // the WebdriverIO browser
+ *   touchTransform: { scale: 3, origin: [0, 132] },       // CSS px -> screen px
+ * });
+ * await solver.solve(page);
+ * ```
+ */
+var humanize_1 = require("./humanize");
+Object.defineProperty(exports, "MouseHumanizer", { enumerable: true, get: function () { return humanize_1.MouseHumanizer; } });
+Object.defineProperty(exports, "MobileHumanizer", { enumerable: true, get: function () { return humanize_1.MobileHumanizer; } });
+Object.defineProperty(exports, "NullHumanizer", { enumerable: true, get: function () { return humanize_1.NullHumanizer; } });
+Object.defineProperty(exports, "BaseHumanizer", { enumerable: true, get: function () { return humanize_1.BaseHumanizer; } });
+Object.defineProperty(exports, "resolveHumanizer", { enumerable: true, get: function () { return humanize_1.resolveHumanizer; } });
+Object.defineProperty(exports, "touchBackendFor", { enumerable: true, get: function () { return humanize_1.touchBackendFor; } });
+Object.defineProperty(exports, "CdpTouchBackend", { enumerable: true, get: function () { return humanize_1.CdpTouchBackend; } });
+Object.defineProperty(exports, "AppiumTouchBackend", { enumerable: true, get: function () { return humanize_1.AppiumTouchBackend; } });
+Object.defineProperty(exports, "TouchscreenTouchBackend", { enumerable: true, get: function () { return humanize_1.TouchscreenTouchBackend; } });
+Object.defineProperty(exports, "PAUSE_KINDS", { enumerable: true, get: function () { return humanize_1.PAUSE_KINDS; } });
+Object.defineProperty(exports, "HUMANIZATION_MODES", { enumerable: true, get: function () { return humanize_1.MODES; } });

package/dist/playwright-types.d.ts

@@ -125,6 +125,24 @@ export interface PlaywrightPage {
     }): Promise<PlaywrightElementHandle | null>;
     /** Current viewport size, or null if not set. */
     viewportSize(): ViewportSize | null;
+    /**
+     * The browser context this page belongs to. OPTIONAL because only
+     * `humanization: 'mobile'` needs it, and then only to open a CDP session for
+     * `Input.dispatchTouchEvent` — the mouse and none modes never touch it. A
+     * launcher that does not expose it simply cannot serve mobile mode, and says
+     * so at construction rather than mid-solve.
+     */
+    context?(): {
+        newCDPSession(page: PlaywrightPage): Promise<any>;
+    };
+    /**
+     * Playwright's touchscreen, present when the context was created with
+     * `hasTouch: true`. OPTIONAL, and tap-only: it is the fallback for a browser
+     * with touch support but no CDP, and cannot express a drag.
+     */
+    touchscreen?: {
+        tap(x: number, y: number): Promise<void>;
+    };
     /** First matching element handle, or null. */
     $(selector: string): Promise<PlaywrightElementHandle | null>;
     /** All matching element handles. */

package/dist/solver.d.ts

@@ -1,5 +1,6 @@
 import { PlaywrightPage as Page, PlaywrightElementHandle as ElementHandle } from './playwright-types';
 import { CaptchaWatcher, WatchOptions } from './watcher';
+import { PhaseBudget } from './timing';
 import { CaptchaKrakenConfig, SolveResult } from './types';
 /**
  * The two numbers that bound a solve, together, because they only make sense
@@ -15,7 +16,15 @@ export declare const SOLVE_DEFAULTS: {
 };
 export declare class CaptchaKrakenSolver {
     private config;
-    private lastMousePosition;
+    /** Extra ms this solve has been granted for a recording; see recordKeyframeBurst. */
+    private videoBudgetMs;
+    private videoBudgetGranted;
+    /**
+     * Every gesture goes through here, and it owns the pointer position. See
+     * humanize.ts — the solver names gestures, this decides what events they are
+     * and how long they take.
+     */
+    private human;
     private imageCounter;
     private sessionDebugDir;
     private stepIndex;
@@ -35,8 +44,47 @@ export declare class CaptchaKrakenSolver {
     private state;
     private lastSubmitFrameHash;
     private solveSessionId;
+    /** Interpreter + CLI root, resolved once. See resolveCli. */
+    private cliCache;
+    /** The LoRA name models.json calls `latest`, read once. See askModel. */
+    private loraNameCache;
+    /**
+     * Phase accounting for the CURRENT or MOST RECENT solve; see timing.ts.
+     * Null before the first solve, and readable after a failed one.
+     */
+    budget: PhaseBudget | null;
+    /**
+     * Attribute the enclosed wall-clock to `name` for this solve's budget.
+     *
+     * A no-op outside a solve, so every helper stays callable from tests and from
+     * the watcher without a budget having been opened.
+     */
+    private ph;
     constructor(config?: CaptchaKrakenConfig);
+    /**
+     * Where the pointer is. Owned by the humanizer, because a mode that
+     * dispatches no motion (mobile, between taps) still has to answer this.
+     */
+    private get lastMousePosition();
+    private set lastMousePosition(value);
     solve(page: Page): Promise<SolveResult | void>;
+    /**
+     * Tell the hosted API whether the widget accepted — the one fact the server
+     * cannot see for itself, since a wrong answer reaches it as a 200 with
+     * well-formed JSON in it.
+     *
+     * THROUGH THE PYTHON CLI, not a `fetch` here. The endpoint, the credential,
+     * the extra-header handling and the "one 404 and stop asking" rule all live
+     * in `planner.report_outcome`; a second copy in TypeScript would agree with
+     * it until one of them was edited. That is the drift `model-name.ts` exists
+     * to prevent, on the same seam, and this port already crosses that subprocess
+     * boundary for every model call.
+     *
+     * NOT AWAITED, and detached. The solve is over and its result is decided, so
+     * nothing here may add latency to what the caller gets back or keep the
+     * process alive past it. `unref()` is what makes the second true.
+     */
+    private reportOutcome;
     /**
      * Install an auto-solver: probe `page` on a timer and solve any captcha that
      * becomes visible, until `stop()`.
@@ -130,6 +178,25 @@ export declare class CaptchaKrakenSolver {
      * `size=invisible` in the src, and never an `api2/bframe` challenge frame, so
      * we exclude the invisible variant here.
      */
+    /**
+     * Which vendors' code this page actually loaded.
+     *
+     * Read out of the page's own resource timing plus the `src`/`href` of
+     * everything it linked, so it works whenever it is called — a request
+     * listener would have to have been attached before navigation, and by the
+     * time a solve fails that ship has sailed.
+     *
+     * Best-effort by construction: the resource-timing buffer is finite and a
+     * page may have cleared it. An empty answer is "nothing seen", never "no
+     * captcha here". Mirrors `vendors_on_the_wire` in page_solver.py.
+     */
+    vendorsOnTheWire(page: Page): Promise<string[]>;
+    /**
+     * Why nothing was found — the two cases told apart. The old text guessed
+     * "reCAPTCHA v3 / invisible" every time, including the times a vendor had
+     * simply moved its DOM. See VENDOR_URL_MARKERS.
+     */
+    private noWidgetMessage;
     hasInteractiveWidgetInDom(page: Page): Promise<boolean>;
     detectCaptcha(page: Page): Promise<ElementHandle | null>;
     /**
@@ -155,6 +222,14 @@ export declare class CaptchaKrakenSolver {
      * falling back to the configured/`python` command. Throws if the CLI folder
      * is missing — callers that must not throw (e.g. runCliTool) wrap this.
      */
+    /**
+     * The adapter name models.json calls `latest`, resolved once per solver.
+     *
+     * `resolveLoraName` reads models.json (and pinned_model.json) off disk
+     * SYNCHRONOUSLY, and it was doing that on every inference for a file that
+     * cannot change inside one process.
+     */
+    private loraName;
     private resolveCli;
     /**
      * Run an OpenCV tool subcommand of the CLI (e.g. `grid-cell-states a.png
@@ -482,17 +557,22 @@ export declare class CaptchaKrakenSolver {
     /**
      * Run `fn` (typically the model query) while idly drifting the cursor over
      * the captcha, so the mouse behaves like a human weighing the options instead
-     * of freezing during inference. Uses the same generate_trajectory paths as real
-     * clicks; cancelled the instant `fn` resolves. Best-effort — any wander error
-     * is swallowed and never fails the solve. Disable via config.idleMouseWander.
+     * of freezing during inference. Uses the same humanizer as real clicks, so a
+     * mode with no cursor skips it entirely; cancelled the instant `fn` resolves.
+     * Best-effort — any wander error is swallowed and never fails the solve.
+     * Disable via config.idleMouseWander.
      */
     private withIdleWander;
     move(page: Page, selectorOrElement: string | ElementHandle, options?: {
         paddingPercentage?: number;
     }): Promise<void>;
     moveAndClick(page: Page, element: ElementHandle): Promise<void>;
+    /**
+     * Travel to a point. What that MEANS is the humanizer's business — on a
+     * touchscreen with no finger down it is a bookkeeping update and emits
+     * nothing at all.
+     */
     private performSmoothMove;
-    private tracePath;
     private executeClick;
     private executeDrag;
     /**
@@ -505,6 +585,30 @@ export declare class CaptchaKrakenSolver {
      * the document, and the answer would go there.
      */
     private findControl;
+    /**
+     * Where a distorted-text captcha's answer goes.
+     *
+     * Inside the widget first. If the widget holds no text box at all, widen ONCE
+     * to its enclosing <fieldset>/<form> and look again for a VENDOR-NAMED box
+     * only.
+     *
+     * BotDetect is why, and nothing else needs it. BotDetect is a self-hosted
+     * LIBRARY, so the host application owns the layout: measured on captcha.com
+     * 2026-08-24, `.BDC_CaptchaDiv` — the element detectCaptcha returns — is
+     * 280x50 and holds the image alone, while `#captchaCode` sits in a sibling
+     * `<div class="validationDiv">` under the enclosing <fieldset>. Scoped to the
+     * widget the solver found no box, textMode stayed false, and it read the code
+     * correctly and never typed it. A clean solve thrown away, and
+     * indistinguishable in any report from a model that cannot read warped text.
+     *
+     * The widened pass is restricted to TEXT_INPUT_VENDOR_SELECTORS on purpose.
+     * The generic tail is what makes the in-widget lookup work for every other
+     * vendor, and OUTSIDE the widget it is exactly how a captcha's answer ends up
+     * in a login form's username box. One level, named selectors, never the page.
+     *
+     * Mirrors `_answer_box` in page_solver.py — CLAUDE.md 1c.
+     */
+    private answerBox;
     /** Put the model's reading of a distorted-text captcha into its box. */
     private executeType;
     /** `captchakraken track-piece` — box of what moved, handle masked out. */
@@ -529,5 +633,11 @@ export declare class CaptchaKrakenSolver {
      * Returns false if there is nothing here to drag, leaving the caller's normal
      * no-op handling to deal with it.
      */
+    /**
+     * Device pixels per CSS pixel, read off the shot we are about to measure.
+     * 1 when the image cannot be read — an unreadable shot is already the
+     * trackPiece-returns-null path, and guessing a ratio would steer by it.
+     */
+    private shotScale;
     private executeSlide;
 }