captchakraken 3.2.1 → 4.0.0

package/dist/humanize.js

@@ -12,8 +12,9 @@
  * motionless tap is a synthetic one.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MODES = exports.NullHumanizer = exports.MobileHumanizer = exports.TouchscreenTouchBackend = exports.AppiumTouchBackend = exports.CdpTouchBackend = exports.MouseHumanizer = exports.BaseHumanizer = exports.PAUSE_KINDS = void 0;
+exports.MODES = exports.NullHumanizer = exports.MobileHumanizer = exports.TouchscreenTouchBackend = exports.AppiumTouchBackend = exports.CdpTouchBackend = exports.MouseHumanizer = exports.BROWSER_PATH_MS = exports.BaseHumanizer = exports.HOLD_POLL_MS = exports.PAUSE_KINDS = exports.MIN_DEVIATION_PX = exports.MAX_DEVIATION = exports.MAX_EVENT_STEP_PX = exports.MAX_EVENT_GAP_MS = exports.gauss = void 0;
 exports.trajectory = trajectory;
+exports.hold = hold;
 exports.touchBackendFor = touchBackendFor;
 exports.resolveHumanizer = resolveHumanizer;
 const cursory_js_1 = require("cursory-js");
@@ -29,19 +30,97 @@ const gauss = (sigma) => {
         u = Math.random();
     return sigma * Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * Math.random());
 };
+exports.gauss = gauss;
 const closedError = (e) => /Target closed|Session closed/.test(e instanceof Error ? e.message : String(e));
-/** A recorded human movement morphed onto the endpoints; timings are cumulative ms. */
+// What one mouse event may cover. cursory's samples are up to 250 ms and 560 px apart, which the page sees as a
+// cursor that vanishes and reappears: a teleport. A real mouse reports every 8 ms (125 Hz).
+exports.MAX_EVENT_GAP_MS = 8;
+exports.MAX_EVENT_STEP_PX = 16;
+// How far a reach may swing off the straight line between its endpoints: a fraction of its length, at least a few
+// pixels. cursory morphs a long recorded movement onto any pair of points, so a 5 px move swung 61 px wide and a
+// 140 px one 300 px.
+exports.MAX_DEVIATION = 0.15;
+exports.MIN_DEVIATION_PX = 3;
+function nearestOnSegment(p, a, b) {
+    const dx = b[0] - a[0], dy = b[1] - a[1];
+    const length2 = dx * dx + dy * dy;
+    if (length2 === 0)
+        return a;
+    const k = Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / length2));
+    return [a[0] + k * dx, a[1] + k * dy];
+}
+/** Shrink the path's swing off the segment, shape kept, until it stays within MAX_DEVIATION of it. */
+function tame(points, start, end) {
+    const limit = Math.max(exports.MIN_DEVIATION_PX, exports.MAX_DEVIATION * Math.hypot(end[0] - start[0], end[1] - start[1]));
+    const near = points.map((p) => nearestOnSegment(p, start, end));
+    const worst = points.reduce((m, p, i) => Math.max(m, Math.hypot(p[0] - near[i][0], p[1] - near[i][1])), 0);
+    if (worst <= limit)
+        return points;
+    const k = limit / worst;
+    return points.map((p, i) => [near[i][0] + (p[0] - near[i][0]) * k, near[i][1] + (p[1] - near[i][1]) * k]);
+}
+/** Fill every gap wider than one mouse report with evenly timed samples along it. */
+function densify(points, timings) {
+    const outP = points.slice(0, 1), outT = timings.slice(0, 1);
+    for (let j = 1; j < points.length; j++) {
+        const a = points[j - 1], b = points[j], ta = timings[j - 1], tb = timings[j];
+        const n = Math.max(1, Math.ceil((tb - ta) / exports.MAX_EVENT_GAP_MS), Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1]) / exports.MAX_EVENT_STEP_PX));
+        for (let i = 1; i <= n; i++) {
+            const f = i / n;
+            outP.push([a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f]);
+            outT.push(ta + (tb - ta) * f);
+        }
+    }
+    return [outP, outT];
+}
+/** A recorded human movement morphed onto the endpoints, held near the line between them and sampled at least
+ * once per mouse report; timings are cumulative ms. */
 function trajectory(start, end, frequency) {
     const { points, timings } = (0, cursory_js_1.generateTrajectory)(start, end, { frequency });
-    return [points.map((q) => [Number(q[0]), Number(q[1])]), timings.map(Number)];
+    const s = [Number(start[0]), Number(start[1])], e = [Number(end[0]), Number(end[1])];
+    return densify(tame(points.map((q) => [Number(q[0]), Number(q[1])]), s, e), timings.map(Number));
 }
 /** Every inter-gesture wait the driver takes, named, so each device supplies its own table. */
 exports.PAUSE_KINDS = Object.values(kinds_js_1.PauseKind);
+/** How often a held press looks at the widget, in ms: a frame hash per look, so not every frame. */
+exports.HOLD_POLL_MS = [180, 320];
+/**
+ * Press at `to` until `done()` says the widget completed, or `maxMs` passes; true when it completed.
+ * Built on move/press/release so any humanizer can hold. The hand drifts a pixel or so meanwhile, because a
+ * press that does not move for seconds is a synthetic one, and the button is released whatever `done` throws.
+ */
+async function hold(human, page, to, done, maxMs) {
+    await human.move(page, to);
+    const anchor = [human.at[0], human.at[1]];
+    await human.press(page);
+    const t0 = Date.now();
+    try {
+        for (;;) {
+            await delay(uniform(exports.HOLD_POLL_MS[0], exports.HOLD_POLL_MS[1]));
+            const to = [anchor[0] + (0, exports.gauss)(0.8), anchor[1] + (0, exports.gauss)(0.8)];
+            await (human.drift ? human.drift(page, to) : human.move(page, to)).catch(() => undefined);
+            if (await done())
+                return true;
+            if (Date.now() - t0 >= maxMs)
+                return false;
+        }
+    }
+    finally {
+        await human.release(page);
+    }
+}
 class BaseHumanizer {
     constructor(start = [0, 0]) {
         this.at = [Number(start[0]), Number(start[1])];
     }
     async reset(_page) { }
+    /**
+     * A held hand's pixel of wander. `move` is a reach, and a reach overshoots: on a 1px move it wandered up to 34px,
+     * off a thin bar, which the widget takes for a release.
+     */
+    async drift(page, to) {
+        await this.move(page, to);
+    }
     /** An unknown kind waits nothing, so adding a pause site cannot break a custom humanizer written against an older release. */
     pauseMs(kind) {
         const range = this.pauses[kind];
@@ -66,6 +145,8 @@ class BaseHumanizer {
     }
 }
 exports.BaseHumanizer = BaseHumanizer;
+/** How much longer than the bare round trip a step takes when the browser re-draws it as a path of its own. */
+exports.BROWSER_PATH_MS = 100;
 class MouseHumanizer extends BaseHumanizer {
     constructor(start = [0, 0], frequency = 60) {
         super(start);
@@ -77,7 +158,10 @@ class MouseHumanizer extends BaseHumanizer {
         };
         this.frequency = frequency;
     }
-    async reset(_page) { this.viewportCache = undefined; }
+    async reset(_page) {
+        this.viewportCache = undefined;
+        this.browserDrawsPath = undefined;
+    }
     /** The window to keep the cursor inside; null under camoufox, which reports no viewport and whose window we ask instead. */
     async viewport(page) {
         if (this.viewportCache !== undefined)
@@ -99,16 +183,60 @@ class MouseHumanizer extends BaseHumanizer {
         }
         return this.viewportCache;
     }
+    async drift(page, to) {
+        try {
+            await page.mouse.move(to[0], to[1]);
+            this.at = [to[0], to[1]];
+        }
+        catch (e) {
+            if (closedError(e))
+                log('could not move mouse; page or session closed');
+        }
+    }
+    /** Clamp only when the viewport is known: a coordinate pinned to the edge of a guessed one deadlocks camoufox's juggler (upstream #225). */
+    async clamp(page, [x, y]) {
+        const viewport = await this.viewport(page);
+        return viewport ? [Math.max(1, Math.min(x, viewport.width - 1)), Math.max(1, Math.min(y, viewport.height - 1))] : [x, y];
+    }
+    /**
+     * Whether the browser draws its own path for every mouse.move(), as camoufox's humanize does. Ours on top has every
+     * sample re-drawn: a 1px step took 190ms there against 1ms, and one GeeTest slider 82s against 13s. One short step
+     * towards `to`, timed against a zero-length move (the bare round trip, so a remote browser is not mistaken for
+     * one), tells them apart with no movement the page could single out.
+     */
+    async measureBrowserPath(page, to) {
+        const from = await this.clamp(page, this.at);
+        const d = Math.hypot(to[0] - from[0], to[1] - from[1]);
+        const step = await this.clamp(page, d <= 3 ? to : [from[0] + 3 * (to[0] - from[0]) / d, from[1] + 3 * (to[1] - from[1]) / d]);
+        try {
+            await page.mouse.move(from[0], from[1]);
+            let t = Date.now();
+            await page.mouse.move(from[0], from[1]);
+            const roundTrip = Date.now() - t;
+            t = Date.now();
+            await page.mouse.move(step[0], step[1]);
+            this.at = step;
+            const drawn = Date.now() - t - roundTrip > exports.BROWSER_PATH_MS;
+            if (drawn)
+                log('the browser draws its own pointer paths (camoufox humanize); handing it one move per gesture');
+            return drawn;
+        }
+        catch (e) {
+            if (closedError(e))
+                log('could not move mouse; page or session closed');
+            return false;
+        }
+    }
     async move(page, to) {
         if (samePoint(this.at, to))
             return;
+        this.browserDrawsPath ?? (this.browserDrawsPath = await this.measureBrowserPath(page, to));
+        if (this.browserDrawsPath)
+            return this.drift(page, await this.clamp(page, to));
         const [points, timings] = trajectory(this.at, to, this.frequency);
-        // Clamp only when the viewport is known: a coordinate pinned to the edge of a guessed one deadlocks camoufox's juggler (upstream #225).
-        const viewport = await this.viewport(page);
         const startTime = Date.now();
         for (let i = 0; i < points.length; i++) {
-            const cx = viewport ? Math.max(1, Math.min(points[i][0], viewport.width - 1)) : points[i][0];
-            const cy = viewport ? Math.max(1, Math.min(points[i][1], viewport.height - 1)) : points[i][1];
+            const [cx, cy] = await this.clamp(page, points[i]);
             try {
                 await page.mouse.move(cx, cy);
             }
@@ -340,6 +468,12 @@ class MobileHumanizer extends BaseHumanizer {
         }
         this.at = dest;
     }
+    async drift(page, to) {
+        const dest = [Number(to[0]), Number(to[1])];
+        if (this.down)
+            await (await this.touch(page)).move([[dest[0], dest[1], 0]]);
+        this.at = dest;
+    }
     async press(page) {
         await (await this.touch(page)).down(this.at[0], this.at[1]);
         this.down = true;
@@ -355,7 +489,7 @@ class MobileHumanizer extends BaseHumanizer {
         const held = this.pauseMs(kinds_js_1.PauseKind.TAP);
         await delay(held / 2);
         try {
-            await (await this.touch(page)).move([[this.at[0] + gauss(0.9), this.at[1] + gauss(0.9), 0]]);
+            await (await this.touch(page)).move([[this.at[0] + (0, exports.gauss)(0.9), this.at[1] + (0, exports.gauss)(0.9), 0]]);
         }
         catch { /* a tap-only backend cannot wobble; the tap still lands */ }
         await delay(held / 2);

package/dist/index.d.ts

@@ -1,16 +1,17 @@
-export * from './types';
-export * from './kinds';
 export { CaptchaKrakenSolver } from './solver';
-export type { Widget } from './solver';
-export { resolveLoraName } from './model-name';
-export { CaptchaKrakenAPIError } from './errors';
-export type { CaptchaKrakenErrorCode } from './errors';
+export { watchPage } from './watcher';
+export type { CaptchaWatcher, WatchOptions, WatchableSolver } from './watcher';
 export { fromPuppeteer } from './puppeteer-adapter';
 export type { Page, PlaywrightPage, PlaywrightFrame, PlaywrightElementHandle, PlaywrightLocator, PlaywrightScope } from './playwright-types';
+export type { CaptchaKrakenConfig } from './types';
+export { DEFAULT_CONFIG_PATH, SelectorConfigError, loadConfig } from './selectors';
+export type { CustomSelectors, DetectorModel, SelectorConfig, SelectorConfigFile, VendorSelectors } from './selectors';
+export { HumanizationMode, PromptFamily, Vendor } from './kinds';
+export type { SolveResult, SolveStepEvent, Vector } from './types';
 export type { RoundVerdict } from './verdicts';
-export { SELECTORS } from './selectors';
-export type { VendorSelectors } from './selectors';
-export { watchPage } from './watcher';
-export type { CaptchaWatcher, WatchOptions, WatchableSolver } from './watcher';
-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';
+export { ErrorCode, FrameRole, Outcome, SolveStage, Verdict } from './kinds';
+export { CaptchaKrakenAPIError } from './errors';
+export type { CaptchaKrakenErrorCode } from './errors';
+export { MobileHumanizer, MouseHumanizer, NullHumanizer } from './humanize';
+export type { Humanizer, Point, TouchBackend, TouchTransform } from './humanize';
+export { PauseKind } from './kinds';

package/dist/index.js

@@ -1,43 +1,35 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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);
-};
+// The published surface: what a caller constructs, configures, receives or implements. Everything else is internal
+// and can change in any release; add a name here only when a caller needs to write it.
 Object.defineProperty(exports, "__esModule", { value: true });
-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.SELECTORS = exports.fromPuppeteer = exports.CaptchaKrakenAPIError = exports.resolveLoraName = exports.CaptchaKrakenSolver = void 0;
-__exportStar(require("./types"), exports);
-__exportStar(require("./kinds"), exports);
+exports.PauseKind = exports.NullHumanizer = exports.MouseHumanizer = exports.MobileHumanizer = exports.CaptchaKrakenAPIError = exports.Verdict = exports.SolveStage = exports.Outcome = exports.FrameRole = exports.ErrorCode = exports.Vendor = exports.PromptFamily = exports.HumanizationMode = exports.loadConfig = exports.SelectorConfigError = exports.DEFAULT_CONFIG_PATH = exports.fromPuppeteer = exports.watchPage = exports.CaptchaKrakenSolver = void 0;
+// Solving
 var solver_1 = require("./solver");
 Object.defineProperty(exports, "CaptchaKrakenSolver", { enumerable: true, get: function () { return solver_1.CaptchaKrakenSolver; } });
-var model_name_1 = require("./model-name");
-Object.defineProperty(exports, "resolveLoraName", { enumerable: true, get: function () { return model_name_1.resolveLoraName; } });
-var errors_1 = require("./errors");
-Object.defineProperty(exports, "CaptchaKrakenAPIError", { enumerable: true, get: function () { return errors_1.CaptchaKrakenAPIError; } });
+var watcher_1 = require("./watcher");
+Object.defineProperty(exports, "watchPage", { enumerable: true, get: function () { return watcher_1.watchPage; } });
 var puppeteer_adapter_1 = require("./puppeteer-adapter");
 Object.defineProperty(exports, "fromPuppeteer", { enumerable: true, get: function () { return puppeteer_adapter_1.fromPuppeteer; } });
 var selectors_1 = require("./selectors");
-Object.defineProperty(exports, "SELECTORS", { enumerable: true, get: function () { return selectors_1.SELECTORS; } });
-var watcher_1 = require("./watcher");
-Object.defineProperty(exports, "watchPage", { enumerable: true, get: function () { return watcher_1.watchPage; } });
+Object.defineProperty(exports, "DEFAULT_CONFIG_PATH", { enumerable: true, get: function () { return selectors_1.DEFAULT_CONFIG_PATH; } });
+Object.defineProperty(exports, "SelectorConfigError", { enumerable: true, get: function () { return selectors_1.SelectorConfigError; } });
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return selectors_1.loadConfig; } });
+var kinds_1 = require("./kinds");
+Object.defineProperty(exports, "HumanizationMode", { enumerable: true, get: function () { return kinds_1.HumanizationMode; } });
+Object.defineProperty(exports, "PromptFamily", { enumerable: true, get: function () { return kinds_1.PromptFamily; } });
+Object.defineProperty(exports, "Vendor", { enumerable: true, get: function () { return kinds_1.Vendor; } });
+var kinds_2 = require("./kinds");
+Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return kinds_2.ErrorCode; } });
+Object.defineProperty(exports, "FrameRole", { enumerable: true, get: function () { return kinds_2.FrameRole; } });
+Object.defineProperty(exports, "Outcome", { enumerable: true, get: function () { return kinds_2.Outcome; } });
+Object.defineProperty(exports, "SolveStage", { enumerable: true, get: function () { return kinds_2.SolveStage; } });
+Object.defineProperty(exports, "Verdict", { enumerable: true, get: function () { return kinds_2.Verdict; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "CaptchaKrakenAPIError", { enumerable: true, get: function () { return errors_1.CaptchaKrakenAPIError; } });
+// Humanizers: the built-in three, and what one of your own implements
 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, "MouseHumanizer", { enumerable: true, get: function () { return humanize_1.MouseHumanizer; } });
 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; } });
+var kinds_3 = require("./kinds");
+Object.defineProperty(exports, "PauseKind", { enumerable: true, get: function () { return kinds_3.PauseKind; } });

package/dist/kinds.d.ts

@@ -2,7 +2,7 @@
  * Every closed set of names the two ports agree on. Mirrored in python/src/captchakraken/kinds.py; keep both in the same order.
  * `as const` objects rather than `enum`: a literal off the wire (`'click'`) type-checks against them, an `enum` would not.
  */
-/** `puzzleSource` everywhere. UNKNOWN must stay permissive: GeeTest and Prosopo report it, and so does the offline grader. */
+/** `puzzleSource` everywhere. UNKNOWN must stay permissive: the CLI, scripts and the offline grader report it. */
 export declare const Vendor: {
     readonly HCAPTCHA: "hcaptcha";
     readonly RECAPTCHA: "recaptcha";
@@ -15,6 +15,12 @@ export declare const Vendor: {
     readonly PROSOPO: "prosopo";
     readonly MTCAPTCHA: "mtcaptcha";
     readonly BOTDETECT: "botdetect";
+    readonly HUMAN: "human";
+    readonly AWSWAF: "awswaf";
+    readonly CAPTCHAFOX: "captchafox";
+    readonly DINGXIANG: "dingxiang";
+    readonly FUNCAPTCHA: "funcaptcha";
+    readonly PROTON: "proton";
     readonly UNKNOWN: "unknown";
 };
 export type Vendor = (typeof Vendor)[keyof typeof Vendor];
@@ -24,6 +30,9 @@ export declare const ActionKind: {
     readonly TYPE: "type";
     readonly WAIT: "wait";
     readonly DONE: "done";
+    readonly HOLD: "hold";
+    readonly REFRESH: "refresh";
+    readonly SLIDE: "slide";
 };
 export type ActionKind = (typeof ActionKind)[keyof typeof ActionKind];
 export declare const RetryMode: {
@@ -104,7 +113,9 @@ export declare const Phase: {
     readonly GRID_LOAD: "grid-load";
     readonly FADE_WAIT: "fade-wait";
     readonly BOARD_PAINT: "board-paint";
-    readonly HCAPTCHA_IMAGES: "hcaptcha-images";
+    readonly BOARD_IMAGES: "board-images";
+    /** @deprecated Use `BOARD_IMAGES`. */
+    readonly HCAPTCHA_IMAGES: "board-images";
     readonly AWAIT_NEXT_ROUND: "await-next-round";
     readonly AWAIT_VERDICT: "await-verdict";
     readonly POST_SUBMIT_DELAY: "post-submit-delay";
@@ -118,6 +129,8 @@ export declare const SolveStage: {
     readonly WAIT: "wait";
     readonly SUBMIT: "submit";
     readonly ROUND: "round";
+    readonly HOLD: "hold";
+    readonly REFRESH: "refresh";
 };
 export type SolveStage = (typeof SolveStage)[keyof typeof SolveStage];
 export declare const FrameRole: {

package/dist/kinds.js

@@ -6,7 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorCode = exports.FrameRole = exports.SolveStage = exports.Phase = exports.Verdict = exports.Outcome = exports.PauseKind = exports.HumanizationMode = exports.PromptFamily = exports.RecaptchaBanner = exports.KeyframeMode = exports.PaintVerdict = exports.SettleVerdict = exports.RetryMode = exports.ActionKind = exports.Vendor = void 0;
 exports.isOneOf = isOneOf;
-/** `puzzleSource` everywhere. UNKNOWN must stay permissive: GeeTest and Prosopo report it, and so does the offline grader. */
+/** `puzzleSource` everywhere. UNKNOWN must stay permissive: the CLI, scripts and the offline grader report it. */
 exports.Vendor = {
     HCAPTCHA: 'hcaptcha',
     RECAPTCHA: 'recaptcha',
@@ -19,9 +19,15 @@ exports.Vendor = {
     PROSOPO: 'prosopo',
     MTCAPTCHA: 'mtcaptcha',
     BOTDETECT: 'botdetect',
+    HUMAN: 'human',
+    AWSWAF: 'awswaf',
+    CAPTCHAFOX: 'captchafox',
+    DINGXIANG: 'dingxiang',
+    FUNCAPTCHA: 'funcaptcha',
+    PROTON: 'proton',
     UNKNOWN: 'unknown',
 };
-exports.ActionKind = { CLICK: 'click', DRAG: 'drag', TYPE: 'type', WAIT: 'wait', DONE: 'done' };
+exports.ActionKind = { CLICK: 'click', DRAG: 'drag', TYPE: 'type', WAIT: 'wait', DONE: 'done', HOLD: 'hold', REFRESH: 'refresh', SLIDE: 'slide' };
 exports.RetryMode = { MISSED_TILES: 'missed-tiles' };
 exports.SettleVerdict = { SETTLED: 'settled', ANIMATED: 'animated', TIMEOUT: 'timeout' };
 exports.PaintVerdict = { PAINTED: 'painted', BLANK: 'blank', UNKNOWN: 'unknown' };
@@ -47,12 +53,14 @@ exports.Phase = {
     GRID_LOAD: 'grid-load',
     FADE_WAIT: 'fade-wait',
     BOARD_PAINT: 'board-paint',
-    HCAPTCHA_IMAGES: 'hcaptcha-images',
+    BOARD_IMAGES: 'board-images',
+    /** @deprecated Use `BOARD_IMAGES`. */
+    HCAPTCHA_IMAGES: 'board-images',
     AWAIT_NEXT_ROUND: 'await-next-round',
     AWAIT_VERDICT: 'await-verdict',
     POST_SUBMIT_DELAY: 'post-submit-delay',
 };
-exports.SolveStage = { INITIAL: 'initial', CLICK: 'click', DRAG: 'drag', TYPE: 'type', WAIT: 'wait', SUBMIT: 'submit', ROUND: 'round' };
+exports.SolveStage = { INITIAL: 'initial', CLICK: 'click', DRAG: 'drag', TYPE: 'type', WAIT: 'wait', SUBMIT: 'submit', ROUND: 'round', HOLD: 'hold', REFRESH: 'refresh' };
 exports.FrameRole = { CHECKBOX: 'checkbox', CHALLENGE: 'challenge', UNKNOWN: 'unknown' };
 /** The hosted API's machine-readable codes. Unknown codes still carry the server's message through; this is not a filter. */
 exports.ErrorCode = {

package/dist/playwright-types.d.ts

@@ -58,6 +58,9 @@ export interface PlaywrightResponse {
     url(): string;
     status(): number;
     text(): Promise<string>;
+    request?(): {
+        resourceType?(): string;
+    };
 }
 /**
  * Structural on purpose: the package depends on no browser library, and the version skew between

package/dist/selectors.d.ts

@@ -1,7 +1,3 @@
-/**
- * Every selector the driver knows, keyed by vendor. Mirrored in python/src/captchakraken/selectors.py; keep both in the
- * same order, because detection takes the first visible match in table order.
- */
 import { FrameRole, RecaptchaBanner, Vendor } from './kinds';
 export interface VendorSelectors {
     /** URL substrings of the vendor's code on the wire. A tripwire, not a detector: the host stays on the wire when a vendor renames its markup (see TRIBAL_KNOWLEDGE.md). BotDetect is self-hosted, so it has none. */
@@ -18,7 +14,10 @@ export interface VendorSelectors {
     readonly response?: string;
     /** Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`. */
     readonly checked?: string;
-    /** Inside the checkbox frame: the box itself, clicked from the DOM. A vendor without one is found on a photograph. */
+    /**
+     * Inside the checkbox frame: the box itself, clicked from the DOM. A vendor without one is found on a photograph.
+     * An in-page checkbox that names one is a button with no tick box to find, and is clicked where it is.
+     */
     readonly box?: readonly string[];
     /** On the host page: the vendor painted its success state. Visibility is part of the test (see TRIBAL_KNOWLEDGE.md). */
     readonly accepted?: string;
@@ -40,24 +39,107 @@ export interface VendorSelectors {
     readonly sliderHandle?: readonly string[];
     /** Inside the widget: the piece, measured to steer the slide and dragged directly when there is no track. */
     readonly piece?: readonly string[];
+    /** Inside the widget: the control that deals a new puzzle, pressed when the model answers `refresh`. */
+    readonly refresh?: readonly string[];
+    /**
+     * A press-and-hold that completes on its own once full, and resets when let go before it has: the fill reaching the
+     * answer's `to` is not a release, and the hold lasts until the widget says it is done.
+     */
+    readonly holdCompletes?: boolean;
+}
+/** A selector config file's shape: the repository's `captchakraken.config.json`, or any part of it. */
+export interface SelectorConfigFile {
+    readonly custom?: Record<string, unknown> | null;
+    readonly vendors?: Record<string, Record<string, unknown>>;
+    readonly generic?: Record<string, readonly string[]>;
+    readonly detector?: DetectorModel;
+    readonly [comment: `_${string}`]: unknown;
+}
+/** A selector config the solver cannot use; the message names the file and the key. */
+export declare class SelectorConfigError extends Error {
+    constructor(message: string);
+}
+/** A loaded selector config: the caller's own entry, every vendor's in detection order, and the generic fallbacks. */
+export interface SelectorConfig {
+    readonly custom: CustomSelectors | null;
+    readonly vendors: ReadonlyArray<readonly [Vendor, VendorSelectors]>;
+    readonly generic: Readonly<Record<GenericKey, readonly string[]>>;
+    /** Which element detector the engine runs: see `DETECTOR_MODELS`. */
+    readonly detector: DetectorModel;
 }
+/**
+ * The element detector's weights: `lite` keeps a board near 100 ms on one vCPU, `standard` is the larger network, and
+ * `auto` takes `lite` on a machine of two CPUs or fewer, else times one board and takes `standard` when it fits.
+ * `CAPTCHA_KRAKEN_DETECTOR_MODEL` in the environment overrides the config.
+ */
+export declare const DETECTOR_MODELS: readonly ["auto", "standard", "lite"];
+export type DetectorModel = (typeof DETECTOR_MODELS)[number];
+declare const GENERIC: readonly ["submit_text", "text_input", "slider_handle", "piece"];
+type GenericKey = (typeof GENERIC)[number];
+/**
+ * The default config: the repository's own `captchakraken.config.json` when this package runs from a checkout, so an
+ * edit there is what the solver reads, else the copy the bundled Python engine ships (an installed package has no
+ * repository root). The Python port resolves the same file.
+ */
+export declare const DEFAULT_CONFIG_PATH: string;
+/**
+ * The shipped default, or `source` (a path or a parsed object) laid over it: a key it gives replaces the default's
+ * `custom`, one vendor's whole entry, or one generic list. Throws SelectorConfigError naming the bad key.
+ */
+export declare function loadConfig(source?: string | SelectorConfigFile): SelectorConfig;
+export declare const DEFAULT_CONFIG: SelectorConfig;
+/** Every vendor's entry, in detection order, as the default config gives it. */
 export declare const SELECTORS: Readonly<Record<Vendor, VendorSelectors>>;
-export declare const VENDORS: ReadonlyArray<readonly [Vendor, VendorSelectors]>;
 export interface WidgetProbe {
     readonly vendor: Vendor;
     readonly role: FrameRole;
     readonly selector: string;
 }
-/** Every host-page selector with what it names, in detection order: open challenges, then checkboxes, then inline widgets. */
-export declare const WIDGET_PROBES: ReadonlyArray<WidgetProbe>;
+/** `.//` keeps the xpath relative so a host-page widget cannot reach the form's own submit. */
+export declare const submitByText: (text: string) => string;
+/** Your own vendor entry: the built-in schema, with `hosts` optional. */
+export type CustomSelectors = Omit<VendorSelectors, 'hosts'> & {
+    readonly hosts?: readonly string[];
+};
+/**
+ * The table one solver detects and drives with: a selector config's vendors, plus its `custom` entry when it has one.
+ * `config` is a path, a parsed object or a loaded SelectorConfig, laid over the shipped default (see `loadConfig`);
+ * `custom` (the older `customSelectors`) replaces the config's own. A custom entry is reported as `Vendor.UNKNOWN` and
+ * searched before the built-in vendors, because the caller wrote it for the page in front of them.
+ */
+export declare class SelectorTable {
+    readonly config: SelectorConfig;
+    readonly selectors: Readonly<Record<Vendor, VendorSelectors>>;
+    readonly vendors: ReadonlyArray<readonly [Vendor, VendorSelectors]>;
+    /** Every host-page selector with what it names, in detection order: open challenges, then checkboxes, then inline widgets. */
+    readonly widgetProbes: ReadonlyArray<WidgetProbe>;
+    readonly enclave: readonly string[];
+    readonly response: readonly string[];
+    readonly accepted: readonly string[];
+    /** A real Verify/Next/Submit/Skip/Confirm first; the vendor-named controls are fallbacks. */
+    readonly submit: readonly string[];
+    readonly textInputVendor: readonly string[];
+    /**
+     * Vendor-named first, generic last: the driver takes the first visible match, and a generic selector reached before
+     * the vendor's own is how a captcha's answer ends up in a login form's username box.
+     */
+    readonly textInput: readonly string[];
+    /** `[draggable=true]` is absent from the generic handles: HTML5 DnD fires dragstart, not pointermove. */
+    readonly sliderHandle: readonly string[];
+    readonly refresh: readonly string[];
+    readonly piece: readonly string[];
+    constructor(custom?: CustomSelectors, config?: string | SelectorConfigFile | SelectorConfig);
+}
+export declare const DEFAULT_TABLE: SelectorTable;
+export declare const VENDORS: readonly (readonly [Vendor, VendorSelectors])[];
+export declare const WIDGET_PROBES: readonly WidgetProbe[];
 export declare const ENCLAVE_SELECTORS: readonly string[];
 export declare const RESPONSE_SELECTORS: readonly string[];
 export declare const ACCEPTED_SELECTORS: readonly string[];
-/** `.//` keeps the xpath relative so a host-page widget cannot reach the form's own submit. */
-export declare const submitByText: (text: string) => string;
-/** A real Verify/Next/Submit/Skip first; the vendor-named controls are fallbacks. */
 export declare const SUBMIT_SELECTORS: readonly string[];
 export declare const TEXT_INPUT_VENDOR_SELECTORS: readonly string[];
 export declare const TEXT_INPUT_SELECTORS: readonly string[];
 export declare const SLIDER_HANDLE_SELECTORS: readonly string[];
+export declare const REFRESH_SELECTORS: readonly string[];
 export declare const PIECE_SELECTORS: readonly string[];
+export {};