captchakraken 2.6.1 → 2.9.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/model-name.d.ts

@@ -9,7 +9,7 @@
  * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
  * `<pkgRoot>/src` (dev), and published packages bundle the engine at
  * `<pkgRoot>/python` (copied in by scripts/copy-python.mjs at build time). In
- * the source monorepo it instead lives at the sibling `../python`.
+ * the source development checkout it instead lives at the sibling `../python`.
  */
 export declare function getBundledCliRoot(): string;
 /**

package/dist/model-name.js

@@ -37,7 +37,7 @@ const node_path_1 = __importDefault(require("node:path"));
  * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
  * `<pkgRoot>/src` (dev), and published packages bundle the engine at
  * `<pkgRoot>/python` (copied in by scripts/copy-python.mjs at build time). In
- * the source monorepo it instead lives at the sibling `../python`.
+ * the source development checkout it instead lives at the sibling `../python`.
  */
 function getBundledCliRoot() {
     const bundled = node_path_1.default.resolve(__dirname, '..', 'python');

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
@@ -9,16 +10,82 @@ import { CaptchaKrakenConfig, SolveResult } from './types';
  * can be pinned by a test — see no-progress.test.ts. The Python port keeps the
  * same pair on `PageSolverConfig`.
  */
+/**
+ * Does this answer need the widget's box to be performed?
+ *
+ * Only a coordinate-bearing action does. `done` means "nothing left to click"
+ * and is the answer a vendor that closes on success will be showing no widget
+ * for, so requiring a box for it fails the solve at the moment it succeeded.
+ *
+ * Written as an ALLOW-LIST of what needs nothing rather than a list of what
+ * does: a new coordinate action added later must default to needing the box,
+ * because that is the direction where being wrong throws instead of clicking
+ * nowhere.
+ */
+export declare function answerNeedsElementBox(actions: ReadonlyArray<{
+    action?: string;
+}>): boolean;
+/**
+ * Is this the challenge TRANSITIONING under us, rather than a dead puzzle?
+ *
+ * hCaptcha swaps in the next round while we hold the old iframe, so a
+ * screenshot on it fails "not visible" / "Timeout" / "not attached". GeeTest
+ * does the mirror image: it CLOSES the panel the moment it accepts an answer,
+ * so the widget we are holding loses its layout box between the screenshot and
+ * the click. Both are the widget moving on, and the answer to both is to
+ * re-detect on the next round rather than to fail the solve.
+ *
+ * The caller gates this on having ALREADY INTERACTED, which is what keeps it
+ * honest: a first-frame failure is a genuine problem and still surfaces.
+ *
+ * Measured 2026-09-07 on gt4.geetest.com — every live GeeTest attempt ended
+ * "Could not get bounding box of captcha element" on a panel the vendor had
+ * just accepted, and each was recorded as the model being wrong.
+ */
+export declare function isStaleHandleError(message: string): boolean;
 export declare const SOLVE_DEFAULTS: {
     readonly maxSolveLoops: 6;
     readonly overallSolveTimeoutMs: 45000;
+    /**
+     * How long to hold a click waiting for the screen the model answered about.
+     *
+     * 9000, not the 6000 it was. A GeeTest svg board dwells p50 1.5s / p75 2.0s /
+     * max 2.7s per screen, so a 3-screen cycle runs 4.5s median and 8.1s worst
+     * case — a 6s budget could not catch the worst case however well aimed, and
+     * gave up one screen short. Named here rather than left as a literal in two
+     * places because `video_budget_ms` is derived from it on both ports and the
+     * arithmetic has to agree.
+     */
+    readonly keyframeWaitTimeoutMs: 9000;
 };
+/**
+ * How long a keyframe burst may run before it is called HUNG.
+ *
+ * A hang detector, not a budget: the solve timeout is what bounds real time.
+ * This only has to notice a screenshot that never returns, so it is
+ * deliberately slack.
+ *
+ * Sized off the CEILING, because that is what sizes the loop — the burst plans
+ * `videoBurstMaxMs` worth of frames, not `videoBurstDurationMs` worth. Must
+ * match `burst_hang_deadline_ms` in the python port, which had this guard
+ * first and had it sized off the floor: a 120-frame burst got 17s, i.e. 141ms
+ * per frame against a 100ms interval, and a burst that simply ran to its
+ * ceiling killed the attempt.
+ */
+export declare function burstHangDeadlineMs(cfg: {
+    videoBurstMaxMs?: number;
+}): number;
 export declare class CaptchaKrakenSolver {
     private config;
     /** Extra ms this solve has been granted for a recording; see recordKeyframeBurst. */
     private videoBudgetMs;
     private videoBudgetGranted;
-    private lastMousePosition;
+    /**
+     * 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;
@@ -32,14 +99,100 @@ export declare class CaptchaKrakenSolver {
     private cvWorkerBuf;
     private solutionCache;
     private repeatedAnswerSeen;
+    /**
+     * The ONE recording and the ONE answer for the animated challenge on screen.
+     *
+     * A cycling board needs a single inference and no more. The burst shows the
+     * model every screen; the answer names the cell AND the screen it is on
+     * (`frame` / `await_keyframe`); the gate then holds the click until that
+     * screen is back up. Nothing about that changes between rounds — the board
+     * keeps cycling through the same pictures with the same target — so asking
+     * again buys nothing and costs a burst plus a multi-image inference.
+     *
+     * It was asking again every round. Loops 3, 4 and 5 each re-recorded and
+     * re-inferred, which is what exhausted a 66s budget on a puzzle whose whole
+     * task is one click.
+     *
+     * Dropped when the gate reports it never saw the chosen screen: that means
+     * the widget is no longer the board this plan was made for, which is exactly
+     * when a fresh recording is warranted.
+     */
+    private animatedPlan;
     private keyframeMode;
+    /**
+     * How many distinct steady screens the current clip sits on; 0 if it is not
+     * that kind of clip. THE GATE KEYS ON THIS, NOT ON `keyframeMode`.
+     *
+     * `even` was being read as "no state recurs, do not wait". It does not mean
+     * that — it means the slicer could not PROVE recurrence, which for a board
+     * whose loop is longer than a 4s burst it never can. 32 of 60 real clips
+     * sliced `even` while sitting on 2-3 steady screens, so the gate was off on
+     * every real animated captcha and the driver clicked whichever screen was up.
+     */
+    private keyframeSteadyScreens;
+    /**
+     * When the current solve must be over, in `Date.now()` terms. 0 outside one.
+     *
+     * The budget used to be checked ONLY at the top of each solve loop, so any
+     * single round could overrun it without limit — and an animated round is the
+     * long one: a 4s burst of 40 element screenshots, a multi-image inference,
+     * then a gated click per target. Measured on GeeTest svg, 2026-09-07: rounds
+     * that re-recorded ran past a 66s budget to the harness's own 180s ceiling
+     * and were reported "hung, not slow", which is a message about the model for
+     * a driver that simply never looked at the clock.
+     *
+     * The Python port has always checked mid-wait (`_check_deadline`), so this
+     * was also a cross-port divergence on exactly the puzzles Tier 3 times.
+     */
+    private solveDeadlineAt;
     private lastAnswerSig;
     private noProgressRounds;
+    /** How far up planner.RESAMPLE_TEMPERATURES this BOARD has escalated. */
+    private resampleLevel;
     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()`.
@@ -72,16 +225,37 @@ export declare class CaptchaKrakenSolver {
     private getVerifyButton;
     private hasNonEmptyFieldValue;
     /**
-     * Detect reCAPTCHA's "Please select all matching images" error banner
-     * (and the related "Please try again" / "Please also check the new images"
-     * variants). These appear in the bframe AFTER clicking Verify with an
-     * incomplete selection. The tiles do NOT refresh on this error — without
-     * special handling the LoRA sees the same image, returns "done" (because
-     * to it everything matching IS selected), we click Verify again, and we
-     * loop until the session times out. We use this signal to switch the next
-     * grid call into "missed-tiles" retry mode.
+     * WHICH of reCAPTCHA's three bframe banners is showing, if any.
+     *
+     * They share a corner and a look and they mean different things:
+     *
+     *   `rejected`      "Please try again."  The answer was wrong; a fresh board
+     *                   follows, so the useful response is to solve that one.
+     *   `select-more`   "Please select all matching images."  Under-selected, and
+     *                   the tiles do NOT refresh — so a driver that re-submits
+     *                   the same answer loops until the session times out. This
+     *                   is the one the missed-tiles retry and the abort exist for.
+     *   `dynamic-more`  "Please also check the new images."  NOT AN ERROR. It is
+     *                   the dynamic 3x3's normal flow: cleared tiles fade out,
+     *                   replacements fade in, and the widget says so — on
+     *                   essentially every round of that variant.
+     *
+     * This used to return a boolean over all three, which made the third one
+     * indistinguishable from the first two and armed the one-retry abort with the
+     * sentence that means "you are doing fine". Every dynamic board therefore
+     * died at round two while the vendor was still dealing. Measured 2026-09-06:
+     * three of three `recaptcha_3x3_fade` attempts stopped at exactly boards=2,
+     * against `recaptcha_4x4` passing at 2, 3 and 5 boards on the same run.
      */
-    private hasRecaptchaUnderselectError;
+    /**
+     * May a repeat of this banner end the solve?
+     *
+     * Only for the banners where repeating means STUCK. `dynamic-more` repeating
+     * means the board is still being cleared, which is progress, and treating it
+     * as fatal is the bug this pair of methods was split to fix.
+     */
+    private bannerIsFatalAfterRetry;
+    private recaptchaBannerKind;
     private isRecaptchaAnchorChecked;
     private isHcaptchaAnchorChecked;
     /**
@@ -133,6 +307,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>;
     /**
@@ -158,6 +351,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
@@ -327,6 +528,28 @@ export declare class CaptchaKrakenSolver {
      * keyframes the wait gate re-reads on every poll live inside it.
      */
     private recordKeyframeBurst;
+    /**
+     * Start recording NOW, and let the caller decide later what it was for.
+     *
+     * This is what makes the speculative path possible. The burst is the only
+     * thing that can tell a cycling board from a still one, and it is also the
+     * recording that answers it — so it is started at the same moment the still
+     * screenshot goes to the model, and the two run together.
+     *
+     *   - the board never moves  -> `moved()` stays false, the still answer is
+     *     used, and the frames are thrown away. The recording cost nothing but
+     *     CPU, because it happened inside an inference we were already waiting
+     *     for.
+     *   - the board moves        -> the still answer is DISCARDED unread, the
+     *     burst runs on to the end of the cycle, and the multi-image answer is
+     *     the one acted on. Two inference CALLS, but only about one inference of
+     *     wall-clock, because the first ran during the recording.
+     *
+     * The old shape paid for that knowledge in whole ROUNDS: answer a still, act
+     * on it, notice nothing changed, answer another still, and only then record.
+     * ~15s of a 40s solve to learn something the first four frames already knew.
+     */
+    private startKeyframeBurst;
     /**
      * Slice a recorded burst into keyframes and solve them in ONE model request.
      *
@@ -362,8 +585,8 @@ export declare class CaptchaKrakenSolver {
      * one-way fade, a sprite crossing — so there is no state to come back to and
      * this can only run out its full 6s, PER CLICK, before clicking the
      * coordinates it already had. It is also the normal case, not a corner: all
-     * 116 real clips under cleanSamples/test/raw are `even` and `cycle` has never
-     * fired on real footage. Measured on hcaptcha_rotating_obj_video: 6.0s of a
+     * 116 real clips under the held-out sample corpus are `even` and `cycle` has never
+     * fired on real footage. Measured on an hCaptcha rotating-object animation: 6.0s of a
      * 28.8s solve, closest region diff 0.0721 against a 0.05 tolerance, then the
      * same click, then solved. Kept for `cycle`/`static`, where the state does
      * come back and waiting is the difference between the sprite and background.
@@ -414,6 +637,20 @@ export declare class CaptchaKrakenSolver {
      * never animated, so escalating there would swap a path that works for one
      * that cannot read a grid.
      */
+    /** Forget the recorded answer, and delete the frames it was holding. */
+    private discardAnimatedPlan;
+    /**
+     * Should this round record while it asks?
+     *
+     * reCAPTCHA is excluded for the same reason it is excluded from the animated
+     * path at all: its dynamic 3x3 REPLACES tiles in place, has its own
+     * multi-round driver with its own fade gates, and its grids are never
+     * animated — so a burst there would film a fade and call it a cycle.
+     *
+     * Distorted-text rounds are excluded because the answer is a string, not a
+     * place, and nothing about a recording helps read one.
+     */
+    private shouldSpeculate;
     private shouldRetryAsAnimated;
     private getSolution;
     /** One inference: build the CLI invocation, run it, parse what comes back. */
@@ -485,17 +722,48 @@ 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;
+    /**
+     * Where in the element this click lands, in element-relative pixels.
+     *
+     * Split out of `executeClick` because on an animated board the point has to
+     * be chosen ONCE and then used three times — to park the pointer, to ask
+     * `match-region` about the right neighbourhood, and to press. Choosing it
+     * inside the click (it is randomised within the target) meant the gate
+     * watched the bbox centre while the press landed somewhere else.
+     */
+    private clickPointFor;
+    /**
+     * Click one target on an ANIMATED board, at the moment its screen is up.
+     *
+     * The order is the point of it. The pointer is parked on the target FIRST,
+     * then the gate opens, then the press happens in place — so the only thing
+     * between "the right screen is showing" and the click is a mouse-down.
+     *
+     * It used to wait and then call `executeClick`, which begins with a humanised
+     * move: 274ms p10 / 398ms p50 / 647ms max across a 340x384 widget, against a
+     * 1500ms median dwell. A quarter to a third of the screen's life spent
+     * travelling after we had already confirmed it was the right one — so the
+     * gate could do its job and the click still land on the next screen.
+     * `move()` short-circuits when it is already at the target, so parking early
+     * costs nothing and removes all of it.
+     */
+    private clickWhenFrameMatches;
     private executeClick;
     private executeDrag;
     /**
@@ -508,6 +776,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. */
@@ -532,5 +824,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;
 }