captchakraken 3.1.0 → 3.2.0

package/AGENTS.md

@@ -8,7 +8,7 @@ It is not a browser and it is not the model. It installs no browser — bring yo
 own launcher — and every inference goes to a model endpoint you point it at.
 
 Repo, guides and the full agent guide:
-<https://github.com/JWriter20/CaptchaKraken>
+<https://github.com/CaptchaKraken/CaptchaKraken>
 
 ---
 
@@ -90,7 +90,7 @@ where one exists. Retrying a `403` that means "no licence" will never succeed.
 
 - **Never invent a number.** Every accuracy, latency and price figure we publish
   is on one page —
-  [docs/benchmarks.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/benchmarks.md).
+  [docs/benchmarks.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/benchmarks.md).
   Quote it as written; do not derive, round, or convert anything, and do not
   read a static-image rate as a promise about a browser run.
 - **Never print an API key** into a transcript, a log, or a commit. Use
@@ -106,7 +106,7 @@ where one exists. Retrying a `403` that means "no licence" will never succeed.
 - **Respect the licence.** Building automation with this is fine; selling the
   solve, or shipping it inside a browser or automation product, is not. See
   [LICENSE](./LICENSE) and
-  [docs/licensing.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/licensing.md).
+  [docs/licensing.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/licensing.md).
 - **Changing this package's own code?** Its rules are in
-  [CONTRIBUTING.md](https://github.com/JWriter20/CaptchaKraken/blob/main/CONTRIBUTING.md),
+  [CONTRIBUTING.md](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/CONTRIBUTING.md),
   not here.

package/LICENSE

@@ -141,5 +141,5 @@ This text is a license, not legal advice. If the boundary between a permitted
 "value-add" product and a prohibited "thin wrapper", or between using the
 Software with a browser and shipping it as part of one, is unclear for your use
 case, ask by opening an issue or messaging the maintainer on GitHub:
-https://github.com/JWriter20/CaptchaKraken
+https://github.com/CaptchaKraken/CaptchaKraken
 --------------------------------------------------------------------------------

package/README.md

@@ -1,12 +1,12 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/JWriter20/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/CaptchaKraken/main/docs/assets/logo-card.png" alt="CaptchaKraken" width="128" height="128">
 </p>
 
 <h1 align="center">captchakraken</h1>
 
 <p align="center">
   <b>A captcha solver for browser automation.</b><br>
-  The TypeScript driver for <a href="https://github.com/JWriter20/CaptchaKraken">CaptchaKraken</a>.
+  The TypeScript driver for <a href="https://github.com/CaptchaKraken/CaptchaKraken">CaptchaKraken</a>.
 </p>
 
 Hand it a Playwright or Puppeteer `Page`. It finds the captcha, reads the whole
@@ -17,27 +17,25 @@ Run the model on **your own hardware**, or point it at the **hosted API** and ru
 nothing at all.
 
 > Full docs — demo videos, accuracy, self-hosting — live in the main repo
-> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
+> **[CaptchaKraken](https://github.com/CaptchaKraken/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"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/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"
+  <img src="https://raw.githubusercontent.com/CaptchaKraken/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**
+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
+**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).
+[main repo](https://github.com/CaptchaKraken/CaptchaKraken#watch-it-work).
 
 ## Install
 
@@ -73,7 +71,6 @@ which the client reads on its own — **no environment variables needed**.
 | Vendor | Puzzles |
 |---|---|
 | **reCAPTCHA** | 3×3 and 4×4 image grids, including the dynamic re-deal |
-| **hCaptcha** | Image grids, click, drag, connect-the-path, tetris-fit, animated |
 | **GeeTest** v3 + v4 | Slide, icon, nine, svg, gobang, iconcrush |
 | **NetEase Yidun** | Jigsaw, picture-click, icon-click |
 | **Tencent, Lemin, Prosopo** | Slide, cropped-image and grid flows |
@@ -149,7 +146,7 @@ somewhere else. A `touchDriver` with no `scale` on a page reporting
 `devicePixelRatio !== 1` refuses on the first gesture and names the value to pass.
 
 Full details, including writing your own humanizer:
-[docs/usage.md § How it moves](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/usage.md#how-it-moves--mouse-mobile-none-or-yours).
+[docs/usage.md § How it moves](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/docs/usage.md#how-it-moves--mouse-mobile-none-or-yours).
 
 ## Configuration
 
@@ -174,7 +171,7 @@ environment variables at all.
 Python engine and spawns it, forwarding the environment wholesale — so every
 variable the engine reads applies to a TypeScript solve too. The full list, and
 the vLLM server knobs, are in
-[AGENTS.md § Environment variables](https://github.com/JWriter20/CaptchaKraken/blob/main/AGENTS.md#environment-variables).
+[AGENTS.md § Environment variables](https://github.com/CaptchaKraken/CaptchaKraken/blob/main/AGENTS.md#environment-variables).
 
 ## License
 

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { CaptchaKrakenAPIError } from './errors';
 export type { CaptchaKrakenErrorCode } from './errors';
 export { fromPuppeteer } from './puppeteer-adapter';
 export type { Page, PlaywrightPage, PlaywrightFrame, PlaywrightElementHandle, PlaywrightLocator, PlaywrightScope } from './playwright-types';
+export type { RoundVerdict } from './verdicts';
 export { SELECTORS } from './selectors';
 export type { VendorSelectors } from './selectors';
 export { watchPage } from './watcher';

package/dist/kinds.d.ts

@@ -84,6 +84,14 @@ export declare const Outcome: {
     readonly FAILED: "failed";
 };
 export type Outcome = (typeof Outcome)[keyof typeof Outcome];
+/** What the vendor's own server answered a round: BLOCKED is a refusal to serve at all, not a wrong answer. */
+export declare const Verdict: {
+    readonly ACCEPTED: "accepted";
+    readonly REJECTED: "rejected";
+    readonly NEW_CHALLENGE: "new-challenge";
+    readonly BLOCKED: "blocked";
+};
+export type Verdict = (typeof Verdict)[keyof typeof Verdict];
 /** Timing phases. Only INFERENCE and MOUSE are productive; everything else is waiting. */
 export declare const Phase: {
     readonly INFERENCE: "inference";

package/dist/kinds.js

@@ -4,7 +4,7 @@
  * `as const` objects rather than `enum`: a literal off the wire (`'click'`) type-checks against them, an `enum` would not.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorCode = exports.FrameRole = exports.SolveStage = exports.Phase = 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.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. */
 exports.Vendor = {
@@ -33,6 +33,8 @@ exports.PromptFamily = { PIXEL: 'pixel', GRID: 'grid', VIDEO: 'video', TEXT: 'te
 exports.HumanizationMode = { MOUSE: 'mouse', MOBILE: 'mobile', NONE: 'none' };
 exports.PauseKind = { TAP: 'tap', BETWEEN: 'between', GRAB: 'grab', DROP: 'drop', PROBE: 'probe', SETTLE: 'settle', KEY: 'key' };
 exports.Outcome = { SOLVED: 'solved', FAILED: 'failed' };
+/** What the vendor's own server answered a round: BLOCKED is a refusal to serve at all, not a wrong answer. */
+exports.Verdict = { ACCEPTED: 'accepted', REJECTED: 'rejected', NEW_CHALLENGE: 'new-challenge', BLOCKED: 'blocked' };
 /** Timing phases. Only INFERENCE and MOUSE are productive; everything else is waiting. */
 exports.Phase = {
     INFERENCE: 'inference',

package/dist/model-name.d.ts

@@ -1,5 +1,11 @@
 export declare function getBundledCliRoot(): string;
 export declare function isHostedEndpoint(baseUrl: string | undefined, env?: NodeJS.ProcessEnv): boolean;
+/** Printed once when a hosted request names a model the endpoint no longer routes; the same text as the Python port's `prompts.LEGACY_MODEL_WARNING`. */
+export declare const LEGACY_MODEL_WARNING: string;
+/** Every name a current client puts on the wire to the hosted API: each routing alias and its expert arms. */
+export declare function routedNames(cliRoot?: string): Set<string>;
+/** A name the hosted API serves with an older model: neither a routing alias nor one of its arms. */
+export declare function isLegacyHostedName(model: string | undefined, cliRoot?: string): boolean;
 /** Hosted: the routing alias, not an arm's `lora_name`, because a routed mixture is several names and only the alias routes. A missing or broken registry falls through to the pin, never throws. */
 export declare function resolveLoraName({ cliRoot, env, baseUrl }?: {
     cliRoot?: string;

package/dist/model-name.js

@@ -3,11 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_MODEL_WARNING = void 0;
 exports.getBundledCliRoot = getBundledCliRoot;
 exports.isHostedEndpoint = isHostedEndpoint;
+exports.routedNames = routedNames;
+exports.isLegacyHostedName = isLegacyHostedName;
 exports.resolveLoraName = resolveLoraName;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const kinds_1 = require("./kinds");
 function getBundledCliRoot() {
     const bundled = node_path_1.default.resolve(__dirname, '..', 'python');
     if (node_fs_1.default.existsSync(bundled))
@@ -31,6 +35,30 @@ function isHostedEndpoint(baseUrl, env = process.env) {
         return false;
     }
 }
+/** Printed once when a hosted request names a model the endpoint no longer routes; the same text as the Python port's `prompts.LEGACY_MODEL_WARNING`. */
+exports.LEGACY_MODEL_WARNING = "The hosted API answers the model name '{model}' with an older model. Remove the model "
+    + 'pin (CAPTCHA_LORA_NAME or the model option) to use the current one.';
+/** Every name a current client puts on the wire to the hosted API: each routing alias and its expert arms. */
+function routedNames(cliRoot = getBundledCliRoot()) {
+    const out = new Set();
+    const reg = readJson(cliRoot, 'models.json');
+    for (const [alias, id] of Object.entries(reg?.served_aliases ?? {})) {
+        if (alias.startsWith('_') || typeof id !== 'string')
+            continue;
+        const declared = reg?.models?.[id]?.experts ?? {};
+        const arms = Object.values(kinds_1.PromptFamily).map((family) => declared[family])
+            .filter((n) => typeof n === 'string' && n !== '');
+        if (arms.length === 0)
+            continue;
+        out.add(alias);
+        arms.forEach((arm) => out.add(arm));
+    }
+    return out;
+}
+/** A name the hosted API serves with an older model: neither a routing alias nor one of its arms. */
+function isLegacyHostedName(model, cliRoot = getBundledCliRoot()) {
+    return !!model && !routedNames(cliRoot).has(model);
+}
 /** Hosted: the routing alias, not an arm's `lora_name`, because a routed mixture is several names and only the alias routes. A missing or broken registry falls through to the pin, never throws. */
 function resolveLoraName({ cliRoot = getBundledCliRoot(), env = process.env, baseUrl } = {}) {
     if (env.CAPTCHA_LORA_NAME)

package/dist/playwright-types.d.ts

@@ -42,6 +42,8 @@ export interface PlaywrightScope {
     locator(selector: string): PlaywrightLocator;
 }
 export interface PlaywrightFrame extends PlaywrightScope {
+    /** Optional: its HOSTNAME alone is sent as X-CK-Widget-Host, the host the widget was served from. */
+    url?(): string;
     waitForSelector(selector: string, options?: {
         state?: 'attached' | 'detached' | 'visible' | 'hidden';
         timeout?: number;
@@ -51,6 +53,12 @@ export interface PlaywrightFrame extends PlaywrightScope {
         polling?: number | 'raf';
     }): Promise<unknown>;
 }
+/** A network response as Playwright and Puppeteer both shape it. */
+export interface PlaywrightResponse {
+    url(): string;
+    status(): number;
+    text(): Promise<string>;
+}
 /**
  * Structural on purpose: the package depends on no browser library, and the version skew between
  * playwright, patchright and camoufox-js makes a nominal import the wrong one for someone.
@@ -84,6 +92,11 @@ export interface PlaywrightPage extends PlaywrightScope {
         timeout?: number;
     }): Promise<PlaywrightElementHandle | null>;
     viewportSize(): ViewportSize | null;
+    /** The whole viewport as a PNG: the driver's only capture, cropped locally, because a clipped one repaints the page. */
+    screenshot(options?: {
+        timeout?: number;
+        animations?: 'disabled' | 'allow';
+    }): Promise<Buffer>;
     /** Optional: the mouse humanizer asks the window for its size when `viewportSize()` is null (camoufox). */
     evaluate?<R>(pageFunction: () => R): Promise<R>;
     context?(): {
@@ -93,5 +106,10 @@ export interface PlaywrightPage extends PlaywrightScope {
         tap(x: number, y: number): Promise<void>;
     };
     isClosed?(): boolean;
+    /** Optional: where the vendor's own verdict is read. Without it every round is judged by the DOM. */
+    on?(event: 'response', listener: (response: PlaywrightResponse) => void): unknown;
+    off?(event: 'response', listener: (response: PlaywrightResponse) => void): unknown;
+    /** Optional: its hostname names the site on hosted requests. */
+    url?(): string;
 }
 export type Page = PlaywrightPage;

package/dist/png.d.ts

@@ -0,0 +1,16 @@
+/** Whole CSS pixels, in viewport coordinates. */
+export interface CaptureRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The whole pixels a bounding box covers: the rect Playwright's element screenshot clips to. */
+export declare function enclosingRect(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): CaptureRect;
+/** Cut `rect` out of a viewport capture `cssWidth` CSS pixels wide, at the capture's own device pixel ratio. */
+export declare function cropPng(png: Buffer, rect: CaptureRect, cssWidth: number): Buffer;

package/dist/png.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enclosingRect = enclosingRect;
+exports.cropPng = cropPng;
+/**
+ * Cutting a rectangle out of a PNG, with nothing but node:zlib. The driver photographs the whole viewport and crops
+ * the widget out of it here, because a clipped browser capture makes a headed Chromium repaint the page.
+ */
+const node_zlib_1 = __importDefault(require("node:zlib"));
+/** The whole pixels a bounding box covers: the rect Playwright's element screenshot clips to. */
+function enclosingRect(box) {
+    const x = Math.floor(box.x + 1e-3);
+    const y = Math.floor(box.y + 1e-3);
+    return { x, y, width: Math.ceil(box.x + box.width - 1e-3) - x, height: Math.ceil(box.y + box.height - 1e-3) - y };
+}
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+// Chunks the pixels cannot be read without: the palette and its transparency, for a colour-type-3 image.
+const CARRIED = new Set(['PLTE', 'tRNS']);
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (const byte of buf)
+        c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length, 0);
+    head.write(type, 4, 'latin1');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+    return Buffer.concat([head, data, crc]);
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+/** Undo the per-row filters of rows [0, rows); a row's filter reads the row above, so the rows above a crop are decoded too. */
+function unfilter(raw, rows, stride, bpp) {
+    const out = [];
+    let prev = Buffer.alloc(stride);
+    for (let y = 0; y < rows; y++) {
+        const at = y * (stride + 1);
+        const filter = raw[at];
+        const line = raw.subarray(at + 1, at + 1 + stride);
+        const cur = Buffer.alloc(stride);
+        for (let i = 0; i < stride; i++) {
+            const left = i >= bpp ? cur[i - bpp] : 0;
+            const up = prev[i];
+            const predict = filter === 0 ? 0
+                : filter === 1 ? left
+                    : filter === 2 ? up
+                        : filter === 3 ? (left + up) >> 1
+                            : filter === 4 ? paeth(left, up, i >= bpp ? prev[i - bpp] : 0)
+                                : NaN;
+            if (Number.isNaN(predict))
+                throw new Error(`PNG row ${y} has unknown filter type ${filter}`);
+            cur[i] = (line[i] + predict) & 0xff;
+        }
+        out.push(cur);
+        prev = cur;
+    }
+    return out;
+}
+/** Cut `rect` out of a viewport capture `cssWidth` CSS pixels wide, at the capture's own device pixel ratio. */
+function cropPng(png, rect, cssWidth) {
+    if (!png.subarray(0, 8).equals(SIGNATURE))
+        throw new Error('not a PNG');
+    let ihdr = null;
+    const idat = [];
+    const carried = [];
+    for (let at = 8; at < png.length;) {
+        const length = png.readUInt32BE(at);
+        const type = png.toString('latin1', at + 4, at + 8);
+        const data = png.subarray(at + 8, at + 8 + length);
+        if (type === 'IHDR')
+            ihdr = data;
+        else if (type === 'IDAT')
+            idat.push(data);
+        else if (CARRIED.has(type))
+            carried.push(chunk(type, data));
+        at += 12 + length;
+    }
+    if (!ihdr)
+        throw new Error('PNG has no IHDR');
+    const width = ihdr.readUInt32BE(0);
+    const bitDepth = ihdr[8];
+    const colorType = ihdr[9];
+    const channels = CHANNELS[colorType];
+    if (!channels || bitDepth < 8 || ihdr[12] !== 0) {
+        throw new Error(`unsupported PNG: colour type ${colorType}, bit depth ${bitDepth}, interlace ${ihdr[12]}`);
+    }
+    const bpp = channels * (bitDepth / 8);
+    const scale = width / cssWidth;
+    const x1 = Math.round(rect.x * scale);
+    const y1 = Math.round(rect.y * scale);
+    const x2 = Math.round((rect.x + rect.width) * scale);
+    const y2 = Math.round((rect.y + rect.height) * scale);
+    const rows = unfilter(node_zlib_1.default.inflateSync(Buffer.concat(idat)), y2, width * bpp, bpp);
+    const cropped = Buffer.concat(rows.slice(y1).flatMap((row) => [Buffer.from([0]), row.subarray(x1 * bpp, x2 * bpp)]));
+    const header = Buffer.from(ihdr);
+    header.writeUInt32BE(x2 - x1, 0);
+    header.writeUInt32BE(y2 - y1, 4);
+    return Buffer.concat([
+        SIGNATURE, chunk('IHDR', header), ...carried, chunk('IDAT', node_zlib_1.default.deflateSync(cropped, { level: 1 })), chunk('IEND', Buffer.alloc(0)),
+    ]);
+}

package/dist/puppeteer-adapter.d.ts

@@ -1,4 +1,4 @@
-import { PlaywrightPage, BoundingBoxRect, ViewportSize } from './playwright-types';
+import { PlaywrightPage, PlaywrightResponse, BoundingBoxRect, ViewportSize } from './playwright-types';
 interface PuppeteerElementHandle {
     screenshot(options?: {
         path?: string;
@@ -33,10 +33,16 @@ interface PuppeteerPage {
     };
     waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
     viewport(): ViewportSize | null;
+    screenshot(options?: {
+        type?: 'png';
+    }): Promise<Uint8Array>;
     evaluate<R>(pageFunction: () => R): Promise<R>;
     $$(selector: string): Promise<PuppeteerElementHandle[]>;
     isClosed(): boolean;
     evaluate(pageFunction: () => any): Promise<any>;
+    on(event: 'response', listener: (response: PlaywrightResponse) => void): unknown;
+    off(event: 'response', listener: (response: PlaywrightResponse) => void): unknown;
+    url(): string;
 }
 export declare function fromPuppeteer(page: PuppeteerPage): PlaywrightPage;
 export {};

package/dist/puppeteer-adapter.js

@@ -75,9 +75,15 @@ function fromPuppeteer(page) {
         waitForTimeout: (timeout) => new Promise((resolve) => setTimeout(resolve, timeout)),
         waitForSelector: async (selector, options) => wrapHandle(await page.waitForSelector(selector, toPuppeteerSelectorOptions(options))),
         viewportSize: () => page.viewport(),
+        // Puppeteer has no `animations` option, and its own timeout; the capture is PNG either way.
+        screenshot: async () => Buffer.from(await page.screenshot({ type: 'png' })),
         evaluate: (pageFunction) => page.evaluate(pageFunction),
         locator: (selector) => locatorOver(() => page.$$(selector)),
         // Forwarded explicitly: without it the watcher polls a dead page forever.
         isClosed: () => page.isClosed(),
+        // Puppeteer's HTTPResponse already has Playwright's url/status/text, so the listener passes straight through.
+        on: (event, listener) => page.on(event, listener),
+        off: (event, listener) => page.off(event, listener),
+        url: () => page.url(),
     };
 }

package/dist/selectors.d.ts

@@ -16,6 +16,8 @@ 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. */
+    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;
     /** Inside the challenge frame: a new round has painted, with text. */
@@ -26,6 +28,10 @@ export interface VendorSelectors {
     readonly submit?: readonly string[];
     /** Inside the challenge frame: verdict banners and what each means. */
     readonly banners?: ReadonlyArray<readonly [string, RecaptchaBanner]>;
+    /** Inside the challenge frame: the vendor refusing to serve this client at all. Nothing after it can succeed. */
+    readonly blocked?: readonly string[];
+    /** On the host page: the vendor's frames that are never interactive, so a page showing only these has no widget. */
+    readonly passive?: readonly string[];
     /** Inside the widget, and its enclosing fieldset/form: the answer box of a typed captcha. */
     readonly textInput?: readonly string[];
     /** Inside the widget: the knob a slide must start on; a drag from the piece moves nothing. */

package/dist/selectors.js

@@ -13,6 +13,7 @@ exports.SELECTORS = {
         checkbox: ['iframe[src*="recaptcha/api2/anchor"]:not([src*="size=invisible"])'],
         response: '[name="g-recaptcha-response"]',
         checked: '.recaptcha-checkbox-checked',
+        box: ['#recaptcha-anchor'],
         fresh: '.rc-imageselect-instructions, #rc-imageselect',
         submit: ['#recaptcha-verify-button'],
         banners: [
@@ -20,6 +21,8 @@ exports.SELECTORS = {
             ['.rc-imageselect-error-dynamic-more', kinds_1.RecaptchaBanner.DYNAMIC_MORE],
             ['.rc-imageselect-incorrect-response', kinds_1.RecaptchaBanner.REJECTED],
         ],
+        blocked: ['.rc-doscaptcha-header-text'],
+        passive: ['iframe[src*="size=invisible"]'],
     },
     // Keyed on the `hcaptcha` substring, not the apex host: challenges are served off newassets.hcaptcha.com.
     [kinds_1.Vendor.HCAPTCHA]: {
@@ -28,6 +31,7 @@ exports.SELECTORS = {
         checkbox: ['iframe[src*="hcaptcha"][src*="frame=checkbox"]'],
         response: '[name="h-captcha-response"]',
         checked: '#checkbox[aria-checked="true"]',
+        box: ['#checkbox'],
         fresh: '.prompt-text',
         images: ['.task-image .image', '.task .image', '.challenge-example img', '.image-wrapper img'],
         submit: ['.button-submit'],

package/dist/solver.d.ts

@@ -20,9 +20,13 @@ export declare function answerNeedsElementBox(actions: ReadonlyArray<{
 }>): boolean;
 /** The widget moved on under us (hCaptcha swapped rounds, GeeTest closed on accept): re-detect, do not fail. */
 export declare function isStaleHandleError(message: string): boolean;
+/** A closed target is not a stale handle: retried as one, a dead page was re-detected until the loops ran out. */
+export declare function isClosedTargetError(message: string): boolean;
+export declare const INPUT_SETTLE_MS = 400;
 export declare const SOLVE_DEFAULTS: {
     readonly maxSolveLoops: 6;
     readonly overallSolveTimeoutMs: 45000;
+    readonly detectionTimeoutMs: 15000;
     readonly keyframeWaitTimeoutMs: 9000;
 };
 /** A hang detector for a burst whose screenshot never returns, sized off the ceiling. */
@@ -44,7 +48,6 @@ export declare class CaptchaKrakenSolver {
     /** Answers keyed by screenshot hash; a hit means the answer already ran and changed nothing. */
     private solutionCache;
     private repeatedAnswerSeen;
-    private retriedUnusableAnswer;
     private knownAnimated;
     private animatedProbeDone;
     /** The one recording for the animated board on screen, and its answer until the widget refuses it. */
@@ -69,24 +72,91 @@ export declare class CaptchaKrakenSolver {
     private actedOnBoard;
     private lastSubmitFrameHash;
     private solveSessionId;
+    /** Which vendor and site this solve is for, sent to the hosted API; the site is a hostname only. */
+    private solveVendor;
+    private solveSite;
+    /** The host the widget itself was served from (its iframe's); null for an inline widget. */
+    private solveWidgetHost;
+    private legacyModelWarned;
+    private verdicts;
+    /** False once a self-hosted endpoint has answered 404: it has no outcome route to report to. */
+    private outcomeSupported;
     private cliCache;
     private loraNameCache;
     budget: PhaseBudget | null;
+    /** The page being solved: every capture is taken of its viewport. Set by `solve`. */
+    private page;
+    /** When our last gesture ended; the board's reaction to it is never read as the board's own motion. */
+    private lastInputAt;
     private ph;
+    /** A pointer gesture, timed as MOUSE and remembered: see `INPUT_SETTLE_MS`. */
+    private gesture;
     constructor(config?: CaptchaKrakenConfig);
     private get lastMousePosition();
     private set lastMousePosition(value);
-    /** `disabled` freezes CSS animation, which once sliced GeeTest svg to a static clip; callers filming motion pass `allow`. */
+    /**
+     * Every capture the driver takes: the whole viewport, cropped here to the element.
+     *
+     * Never a clipped capture. An element screenshot, or any `clip`, makes a headed Chromium repaint the page at the
+     * clip's size for that frame, which the user watches as the page flashing and jumping; a viewport capture
+     * repaints nothing, and measured twice as fast. `disabled` freezes CSS animation, which once sliced GeeTest svg to
+     * a static clip; callers filming motion pass `allow`.
+     */
     private shot;
+    private rectOf;
+    /** Where the element sits in the viewport, scrolled in when it is merely off screen; null when it cannot fit. */
+    private rectInView;
+    /**
+     * Take the pointer off the board and let our own feedback fade before the board is judged still or animated.
+     *
+     * A hovered or pressed control repaints, and a board wearing our highlight read as motion: a still board was
+     * filmed as animated because of the Verify button under the cursor.
+     */
+    private stepOffTheBoard;
     solve(page: Page): Promise<SolveResult | void>;
-    /** Tell the hosted API whether the widget accepted, through the CLI, detached, never awaited. */
+    /** Tell the hosted API whether the widget accepted, through the CLI. The solve never awaits it; the promise is for callers that must know it finished. */
     private reportOutcome;
     /** Solve captchas on `page` as they appear, until `stop()`. Injects nothing into the page. */
     watch(page: Page, options?: WatchOptions): CaptchaWatcher;
+    /**
+     * Give up only when the vendor refuses to serve us, or when every one of `maxSolveLoops` has been spent. Any other
+     * failed round — a stale handle, an unusable or repeated answer, a board that would not film — counts one loop,
+     * pauses, and goes again.
+     */
     private solveImpl;
+    /** What the vendor's server said since the last look: BLOCKED outranks everything, else the latest answer. */
+    private vendorVerdict;
+    /**
+     * A page that has not drawn its widget yet is looked at again until `detectionTimeoutMs`. Solving straight after
+     * `domcontentloaded` failed 3/3 on a demo page whose frames arrived a moment later.
+     */
+    private awaitWidget;
+    /** The vendor showing its refusal screen: rate-limited or flagged, with no board to answer. */
+    private isBlocked;
+    /** The env the engine reads its routing headers from: session, and the vendor and site once they are known. */
+    private routingEnv;
     /** Fire the optional onStep observer with a fresh screenshot; best-effort, never fails the solve. */
     private emitStep;
     private solveSingle;
+    /**
+     * Tick the box and wait for what it opens. A checkbox is not a board: it is never polled, filmed or asked about.
+     *
+     * Treated as a board it cost 70 screenshots and three model calls in one measured solve, two of them answering the
+     * checkbox picture with a drag.
+     */
+    private clickCheckbox;
+    /**
+     * The box in a checkbox frame once the frame has drawn it; null when the DOM cannot reach it. Turnstile's box is in
+     * a closed shadow root, and a frame can refuse access; both are found on screen instead.
+     */
+    private checkboxBox;
+    /** One capture and OpenCV: a point inside the tick box, in page coordinates. No model is asked. */
+    private findCheckboxOnScreen;
+    /**
+     * A clicked checkbox passes or opens a challenge, and both show in the DOM.
+     * Without this wait the next round found the same checkbox still up and clicked it again.
+     */
+    private awaitWhatTheCheckboxOpened;
     private getVerifyButton;
     /** Any element at `selector` carrying a non-blank value; response fields are hidden, so no visibility filter. */
     private hasValue;
@@ -107,6 +177,8 @@ export declare class CaptchaKrakenSolver {
     private waitForBoardImages;
     /** Which vendors' code the page loaded, from resource timing and linked URLs. A tripwire, not a detector. */
     vendorsOnTheWire(page: Page): Promise<Vendor[]>;
+    /** Vendors showing a frame no selector names. Only asked once detection has found nothing, and a passive frame (an invisible badge) is not a widget, so what is left is markup the table no longer matches. */
+    private unmatchedVendorFrames;
     private noWidgetMessage;
     /**
      * Is a widget in the DOM at all, rendered or not? Invisible reCAPTCHA is excluded by its selector. The inline vendors
@@ -180,7 +252,7 @@ export declare class CaptchaKrakenSolver {
     private startKeyframeBurst;
     /** Slice a burst into keyframes and solve them in one model request. The frame number is the guard. */
     private getAnimatedSolution;
-    /** The session id and the credential travel in the environment, never in argv. */
+    /** The routing values and the credential travel in the environment, never in argv. */
     private solveEnvironment;
     /** Exit 2 is an unsupported puzzle, exit 3 the hosted API's own refusal; both are relayed, not reworded. */
     private cliError;