captchakraken 2.8.0 → 3.0.0

package/dist/model-name.js

@@ -4,41 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBundledCliRoot = getBundledCliRoot;
+exports.isHostedEndpoint = isHostedEndpoint;
 exports.resolveLoraName = resolveLoraName;
-/**
- * Which served LoRA name this client asks for — the SAME answer the Python
- * client's `config.lora_name()` gives, and for the same reasons.
- *
- * This has to be shared, not re-decided per port. The name is not just routing:
- * the Python CLI feeds it to `prompts.resolve()`, which maps it through
- * models.json to a PROMPT GENERATION. A port that picks a different name sends
- * a different generation of prompts to the same weights, and nothing errors for
- * any family both generations have a prompt for — it just answers worse. That
- * is the failure models.json exists to prevent, and the JS port shipped it:
- * a hardcoded `'captcha'` (CaptchaKraken_v1.1, generation 1) against the
- * generation-2 adapter `latest` has named since v1.2.
- *
- * Precedence mirrors config.py exactly:
- *   1. CAPTCHA_LORA_NAME — an explicit pin always wins, and pinning is opt-in.
- *   2. models.json's `latest` entry, so the default model and the default
- *      prompt generation move forward together and cannot get out of step.
- *   3. pinned_model.json, so a hand-edited or older manifest still resolves.
- */
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-/**
- * Where the bundled Python engine lives — the copy of `models.json` this client
- * actually answers from.
- *
- * Lives HERE rather than in solver.ts because the registry lookup below is its
- * only remaining caller-visible use, and a second copy of this path logic is
- * how the two ports drifted apart in the first place. solver.ts imports it.
- *
- * 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`.
- */
 function getBundledCliRoot() {
     const bundled = node_path_1.default.resolve(__dirname, '..', 'python');
     if (node_fs_1.default.existsSync(bundled))
@@ -48,23 +17,46 @@ function getBundledCliRoot() {
 function readJson(cliRoot, name) {
     return JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cliRoot, 'src', 'captchakraken', name), 'utf-8'));
 }
-/**
- * `cliRoot` is optional so a caller that only wants to REPORT the name — a test
- * harness recording which adapter it drove — can ask without reconstructing the
- * engine's layout. Re-deriving it is the same mistake one level down.
- */
-function resolveLoraName({ cliRoot = getBundledCliRoot(), env = process.env } = {}) {
+// An exact host list, not "is it remote": a self-hoster's vLLM across the network is remote too, and the hosted-only model 404s there.
+const HOSTED_HOSTS = ['api.captchakraken.com'];
+function isHostedEndpoint(baseUrl, env = process.env) {
+    if (!baseUrl)
+        return false;
+    const extra = (env.CAPTCHA_HOSTED_HOSTS ?? '')
+        .split(',').map((h) => h.trim().toLowerCase()).filter(Boolean);
+    try {
+        return [...HOSTED_HOSTS, ...extra].includes(new URL(baseUrl).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/** 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)
         return env.CAPTCHA_LORA_NAME;
     try {
         const reg = readJson(cliRoot, 'models.json');
+        if (isHostedEndpoint(baseUrl, env)) {
+            const repo = reg?.hosted_default;
+            if (typeof repo === 'string' && repo) {
+                const aliases = Object.entries(reg?.served_aliases ?? {})
+                    .filter(([a, target]) => target === repo && !a.startsWith('_'))
+                    .map(([a]) => a);
+                const routed = aliases.find((a) => {
+                    const id = (reg?.served_aliases ?? {})[a];
+                    return Object.keys(reg?.models?.[id]?.experts ?? {}).length > 0;
+                });
+                const picked = routed ?? aliases[0] ?? reg?.models?.[repo]?.lora_name;
+                if (typeof picked === 'string' && picked)
+                    return picked;
+            }
+        }
         const name = reg?.models?.[reg?.latest]?.lora_name;
         if (typeof name === 'string' && name)
             return name;
     }
     catch {
-        // A missing or broken registry falls through to the pin, never throws —
-        // same contract as config.py's `_registry_default`.
     }
     return readJson(cliRoot, 'pinned_model.json').lora_name;
 }

package/dist/playwright-types.d.ts

@@ -1,95 +1,61 @@
-/**
- * Minimal, implementation-neutral structural types for the slice of the
- * Playwright API the solver actually uses.
- *
- * **Why these exist.** CaptchaKraken never launches a browser — you bring your
- * own Playwright-compatible launcher and hand `solve()` a `Page`. To stay truly
- * browser-agnostic the package depends on NO concrete browser implementation
- * (not `playwright`, not `patchright`, not `camoufox-js`). Typing the public API
- * against any one of those packages' `Page` would (a) force that package into
- * consumers' trees and (b) break across version skew — e.g. `patchright` pins
- * its own forked, older core whose `Page` is missing the newest `playwright-core`
- * methods, so a `patchright` page won't structurally match a `playwright-core`
- * page and vice-versa.
- *
- * Instead we declare a duck-typed surface covering only what the solver calls.
- * Every real Playwright `Page` / `Frame` / `ElementHandle` — from vanilla
- * `playwright`, `patchright`, `camoufox-js`, or anything else — structurally
- * satisfies these, regardless of which Playwright version it was built against.
- *
- * Keep these in sync with `solver.ts`: if the solver starts calling a new
- * Playwright method, add it here. The set is intentionally small and stable —
- * these are long-standing Playwright primitives, not bleeding-edge additions.
- */
-/** `{ x, y, width, height }` in CSS pixels — the shape `boundingBox()` returns. */
 export interface BoundingBoxRect {
     x: number;
     y: number;
     width: number;
     height: number;
 }
-/** `{ width, height }` — the shape `viewportSize()` returns. */
 export interface ViewportSize {
     width: number;
     height: number;
 }
-/**
- * Structural subset of Playwright's `ElementHandle`. Returned by `Page.$` /
- * `Frame.$` / `Page.waitForSelector` and accepted by the solver as the captcha
- * element / verify button / iframe handle.
- */
 export interface PlaywrightElementHandle {
-    /** Screenshot just this element to a PNG file (the only option the solver passes). */
     screenshot(options?: {
         path?: string;
         timeout?: number;
         animations?: 'disabled' | 'allow';
     }): Promise<Buffer>;
-    /** The content document of an `<iframe>` element handle, or null if not a frame. */
     contentFrame(): Promise<PlaywrightFrame | null>;
-    /** Element box in page CSS pixels, or null if not rendered. */
     boundingBox(): Promise<BoundingBoxRect | null>;
-    /** Scroll the element into view if it isn't already. */
     scrollIntoViewIfNeeded(options?: {
         timeout?: number;
     }): Promise<void>;
-    /** Read an attribute, or null if absent. */
     getAttribute(name: string): Promise<string | null>;
-    /** Whether the element is visible. */
     isVisible(): Promise<boolean>;
-    /** The element's text content, or null. */
     textContent(): Promise<string | null>;
-    /**
-     * First matching element WITHIN this element's subtree, or null. The vendors
-     * that render into the host page rather than an iframe (GeeTest, Yidun,
-     * BotDetect, …) have no Frame to scope against, so the widget element is the
-     * boundary that keeps a generic selector off the rest of the document.
-     */
-    $(selector: string): Promise<PlaywrightElementHandle | null>;
+    inputValue(): Promise<string>;
+    evaluate<R>(pageFunction: (element: Element) => R): Promise<R>;
 }
-/**
- * Structural subset of Playwright's `Frame` (an iframe's content document).
- */
-export interface PlaywrightFrame {
-    /** First matching element handle, or null. */
-    $(selector: string): Promise<PlaywrightElementHandle | null>;
-    /** Wait for a selector to reach the given state; resolves to the handle (or null). */
+/** The subset of Playwright's Locator the driver needs. `filter({ visible })` is Playwright 1.51+. */
+export interface PlaywrightLocator {
+    locator(selector: string): PlaywrightLocator;
+    filter(options: {
+        visible?: boolean;
+    }): PlaywrightLocator;
+    all(): Promise<PlaywrightLocator[]>;
+    count(): Promise<number>;
+    elementHandle(options?: {
+        timeout?: number;
+    }): Promise<PlaywrightElementHandle | null>;
+}
+/** Anything selectors can be run inside: a page, a frame, or the locator of an inline widget. */
+export interface PlaywrightScope {
+    locator(selector: string): PlaywrightLocator;
+}
+export interface PlaywrightFrame extends PlaywrightScope {
     waitForSelector(selector: string, options?: {
         state?: 'attached' | 'detached' | 'visible' | 'hidden';
         timeout?: number;
     }): Promise<PlaywrightElementHandle | null>;
-    /** Poll a predicate evaluated in the page until it returns truthy. */
     waitForFunction(pageFunction: Function | string, arg?: any, options?: {
         timeout?: number;
         polling?: number | 'raf';
     }): Promise<unknown>;
 }
 /**
- * Structural subset of Playwright's `Page` — exactly the members `solve()` and
- * its helpers call. Any real Playwright `Page` satisfies this.
+ * 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.
  */
-export interface PlaywrightPage {
-    /** Low-level mouse control used to drive human-like trajectories and clicks. */
+export interface PlaywrightPage extends PlaywrightScope {
     mouse: {
         move(x: number, y: number, options?: {
             steps?: number;
@@ -103,11 +69,7 @@ export interface PlaywrightPage {
             clickCount?: number;
         }): Promise<void>;
     };
-    /**
-     * Key input. Used to type a distorted-text captcha's answer character by
-     * character — `fill()` would set the value with no keystrokes at all, and
-     * these are the vendors that score typing cadence.
-     */
+    /** `type` is called per character by the humanizer; a constant `delay` would itself be a signal. */
     keyboard: {
         type(text: string, options?: {
             delay?: number;
@@ -116,52 +78,20 @@ export interface PlaywrightPage {
             delay?: number;
         }): Promise<void>;
     };
-    /** Sleep `timeout` ms (Playwright's own timer). */
     waitForTimeout(timeout: number): Promise<void>;
-    /** Wait for a selector to reach the given state; resolves to the handle (or null). */
     waitForSelector(selector: string, options?: {
         state?: 'attached' | 'detached' | 'visible' | 'hidden';
         timeout?: number;
     }): 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.
-     */
+    /** Optional: the mouse humanizer asks the window for its size when `viewportSize()` is null (camoufox). */
+    evaluate?<R>(pageFunction: () => R): Promise<R>;
     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. */
-    $$(selector: string): Promise<PlaywrightElementHandle[]>;
-    /**
-     * Whether the page has been closed. OPTIONAL because it is the one member
-     * here the solver itself never needs — the auto-solve watcher uses it to end
-     * its loop when the caller closes the browser out from under it, and falls
-     * back to treating the page as open when a launcher does not expose it.
-     * Playwright and Puppeteer both do.
-     */
     isClosed?(): boolean;
-    /** Run `pageFunction` against the first matching element, in the page context. */
-    $eval<R>(selector: string, pageFunction: (element: Element) => R, arg?: any): Promise<R>;
 }
-/**
- * Public alias. This is the type the solver's `solve(page)` accepts — kept under
- * a friendly name so consumers can annotate against it. It is the
- * implementation-neutral Playwright `Page`; pass a page from whichever
- * Playwright-compatible launcher you prefer.
- */
 export type Page = PlaywrightPage;

package/dist/playwright-types.js

@@ -1,25 +1,2 @@
 "use strict";
-/**
- * Minimal, implementation-neutral structural types for the slice of the
- * Playwright API the solver actually uses.
- *
- * **Why these exist.** CaptchaKraken never launches a browser — you bring your
- * own Playwright-compatible launcher and hand `solve()` a `Page`. To stay truly
- * browser-agnostic the package depends on NO concrete browser implementation
- * (not `playwright`, not `patchright`, not `camoufox-js`). Typing the public API
- * against any one of those packages' `Page` would (a) force that package into
- * consumers' trees and (b) break across version skew — e.g. `patchright` pins
- * its own forked, older core whose `Page` is missing the newest `playwright-core`
- * methods, so a `patchright` page won't structurally match a `playwright-core`
- * page and vice-versa.
- *
- * Instead we declare a duck-typed surface covering only what the solver calls.
- * Every real Playwright `Page` / `Frame` / `ElementHandle` — from vanilla
- * `playwright`, `patchright`, `camoufox-js`, or anything else — structurally
- * satisfies these, regardless of which Playwright version it was built against.
- *
- * Keep these in sync with `solver.ts`: if the solver starts calling a new
- * Playwright method, add it here. The set is intentionally small and stable —
- * these are long-standing Playwright primitives, not bleeding-edge additions.
- */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/puppeteer-adapter.d.ts

@@ -1,38 +1,3 @@
-/**
- * Puppeteer → CaptchaKraken adapter.
- *
- * The solver speaks the Playwright API surface (see playwright-types.ts). Puppeteer
- * is ~95% the same shape but differs in a handful of method names/options. Rather
- * than couple the solver to either library, this thin adapter wraps a Puppeteer
- * `Page` (and, lazily, the `Frame`/`ElementHandle` objects it hands back) so it
- * satisfies the structural `PlaywrightPage` interface the solver consumes.
- *
- * The deltas it bridges (verified against Puppeteer 24.x):
- *   - `page.viewportSize()`            → `page.viewport()`  (same `{width,height}` shape)
- *   - `page.waitForTimeout(ms)`        → removed in modern Puppeteer; use a timer
- *   - `*.waitForSelector(sel, {state}) → Puppeteer uses `{visible}/{hidden}`
- *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
- *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
- *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
- *   - `page.isClosed()`                → same, but must be forwarded explicitly
- * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
- * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
- * call-compatible and passed straight through.
- *
- * Usage:
- * ```typescript
- * import puppeteer from 'puppeteer';
- * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
- *
- * const browser = await puppeteer.launch({ headless: false });
- * const page = await browser.newPage();
- * await page.goto('https://www.google.com/recaptcha/api2/demo');
- *
- * const solver = new CaptchaKrakenSolver();
- * await solver.solve(fromPuppeteer(page));
- * await browser.close();
- * ```
- */
 import { PlaywrightPage, BoundingBoxRect, ViewportSize } from './playwright-types';
 interface PuppeteerElementHandle {
     screenshot(options?: {
@@ -43,10 +8,10 @@ interface PuppeteerElementHandle {
     scrollIntoView(): Promise<void>;
     isVisible(): Promise<boolean>;
     evaluate(pageFunction: (el: any, ...args: any[]) => any, ...args: any[]): Promise<any>;
-    $(selector: string): Promise<PuppeteerElementHandle | null>;
+    $$(selector: string): Promise<PuppeteerElementHandle[]>;
 }
 interface PuppeteerFrame {
-    $(selector: string): Promise<PuppeteerElementHandle | null>;
+    $$(selector: string): Promise<PuppeteerElementHandle[]>;
     waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
     waitForFunction(pageFunction: Function | string, options?: any, ...args: any[]): Promise<unknown>;
 }
@@ -68,14 +33,10 @@ interface PuppeteerPage {
     };
     waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
     viewport(): ViewportSize | null;
-    $(selector: string): Promise<PuppeteerElementHandle | null>;
+    evaluate<R>(pageFunction: () => R): Promise<R>;
     $$(selector: string): Promise<PuppeteerElementHandle[]>;
-    $eval(selector: string, pageFunction: (element: Element) => any, ...args: any[]): Promise<any>;
     isClosed(): boolean;
+    evaluate(pageFunction: () => any): Promise<any>;
 }
-/**
- * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright
- * `Page`. Pass the result to `solver.solve(...)`.
- */
 export declare function fromPuppeteer(page: PuppeteerPage): PlaywrightPage;
 export {};

package/dist/puppeteer-adapter.js

@@ -1,42 +1,6 @@
 "use strict";
-/**
- * Puppeteer → CaptchaKraken adapter.
- *
- * The solver speaks the Playwright API surface (see playwright-types.ts). Puppeteer
- * is ~95% the same shape but differs in a handful of method names/options. Rather
- * than couple the solver to either library, this thin adapter wraps a Puppeteer
- * `Page` (and, lazily, the `Frame`/`ElementHandle` objects it hands back) so it
- * satisfies the structural `PlaywrightPage` interface the solver consumes.
- *
- * The deltas it bridges (verified against Puppeteer 24.x):
- *   - `page.viewportSize()`            → `page.viewport()`  (same `{width,height}` shape)
- *   - `page.waitForTimeout(ms)`        → removed in modern Puppeteer; use a timer
- *   - `*.waitForSelector(sel, {state}) → Puppeteer uses `{visible}/{hidden}`
- *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
- *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
- *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
- *   - `page.isClosed()`                → same, but must be forwarded explicitly
- * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
- * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
- * call-compatible and passed straight through.
- *
- * Usage:
- * ```typescript
- * import puppeteer from 'puppeteer';
- * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
- *
- * const browser = await puppeteer.launch({ headless: false });
- * const page = await browser.newPage();
- * await page.goto('https://www.google.com/recaptcha/api2/demo');
- *
- * const solver = new CaptchaKrakenSolver();
- * await solver.solve(fromPuppeteer(page));
- * await browser.close();
- * ```
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromPuppeteer = fromPuppeteer;
-/** Translate Playwright `{state}` selector options to Puppeteer `{visible}/{hidden}`. */
 function toPuppeteerSelectorOptions(options) {
     if (!options)
         return undefined;
@@ -48,10 +12,22 @@ function toPuppeteerSelectorOptions(options) {
         out.visible = true;
     else if (state === 'hidden')
         out.hidden = true;
-    // 'attached'/'detached' have no direct Puppeteer flag — default wait (attached)
-    // is the closest match, so we pass no visibility flag.
     return out;
 }
+/** Puppeteer's own Locator has no `all()`, `count()` or visibility filter, so a Playwright-shaped one is built over `$$`. */
+function locatorOver(resolve) {
+    return {
+        locator: (selector) => locatorOver(async () => (await Promise.all((await resolve()).map((h) => h.$$(selector)))).flat()),
+        filter: ({ visible }) => locatorOver(async () => {
+            const found = await resolve();
+            const shown = await Promise.all(found.map((h) => (visible === undefined ? true : h.isVisible().then((v) => v === visible))));
+            return found.filter((_, i) => shown[i]);
+        }),
+        all: async () => (await resolve()).map((h) => locatorOver(async () => [h])),
+        count: async () => (await resolve()).length,
+        elementHandle: async () => wrapHandle((await resolve())[0] ?? null),
+    };
+}
 function wrapHandle(h) {
     if (!h)
         return null;
@@ -63,24 +39,19 @@ function wrapHandle(h) {
         getAttribute: (name) => h.evaluate((el, n) => el.getAttribute(n), name),
         isVisible: () => h.isVisible(),
         textContent: () => h.evaluate((el) => el.textContent),
-        $: async (selector) => wrapHandle(await h.$(selector)),
+        inputValue: () => h.evaluate((el) => (typeof el.value === 'string' ? el.value : '')),
+        evaluate: (pageFunction) => h.evaluate(pageFunction),
     };
 }
 function wrapFrame(f) {
     if (!f)
         return null;
     return {
-        $: async (selector) => wrapHandle(await f.$(selector)),
+        locator: (selector) => locatorOver(() => f.$$(selector)),
         waitForSelector: async (selector, options) => wrapHandle(await f.waitForSelector(selector, toPuppeteerSelectorOptions(options))),
-        waitForFunction: (pageFunction, arg, options) => 
-        // Playwright: (fn, arg, {timeout,polling}); Puppeteer: (fn, {timeout,polling}, ...args).
-        f.waitForFunction(pageFunction, options, arg),
+        waitForFunction: (pageFunction, arg, options) => f.waitForFunction(pageFunction, options, arg),
     };
 }
-/**
- * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright
- * `Page`. Pass the result to `solver.solve(...)`.
- */
 function fromPuppeteer(page) {
     return {
         mouse: {
@@ -90,9 +61,7 @@ function fromPuppeteer(page) {
         },
         keyboard: {
             type: (text, options) => page.keyboard.type(text, options),
-            // Puppeteer has no combo syntax: 'Control+A' must be held, pressed,
-            // released. Playwright accepts the combo string directly, which is why
-            // the solver speaks Playwright and this adapter translates.
+            // Puppeteer has no 'Control+A' combo syntax; the solver speaks Playwright and this side translates.
             press: async (key) => {
                 const parts = key.split('+');
                 const target = parts.pop();
@@ -106,14 +75,9 @@ 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(),
-        $: async (selector) => wrapHandle(await page.$(selector)),
-        $$: async (selector) => (await page.$$(selector)).map((h) => wrapHandle(h)).filter(Boolean),
-        $eval: (selector, pageFunction, arg) => page.$eval(selector, pageFunction, arg),
-        // Same name and shape on both libraries, but it still has to be forwarded:
-        // the wrapper is a fresh object literal, so anything not listed here is
-        // simply absent. The auto-solve watcher reads it to end its loop when the
-        // caller closes the browser, and an undefined `isClosed` reads as "still
-        // open" — a watcher that polls a dead page forever.
+        evaluate: (pageFunction) => page.evaluate(pageFunction),
+        locator: (selector) => locatorOver(() => page.$$(selector)),
+        // Forwarded explicitly: without it the watcher polls a dead page forever.
         isClosed: () => page.isClosed(),
     };
 }

package/dist/python-command.d.ts

@@ -1,50 +1,9 @@
-/**
- * Which interpreter runs the bundled CaptchaKraken CLI.
- *
- * This used to be `pythonCommand = 'python'`, inline in solver.ts. On
- * Debian/Ubuntu — the most common Linux deployment target, and what CI runs —
- * there is no `python` on PATH at all, only `python3`. So every JS solve died
- * with `/bin/sh: 1: python: not found` before it ever reached the model, unless
- * a `.venv` happened to exist next to the package. The type doc claimed the
- * default was "'python' or 'python3'"; the code never tried `python3`.
- *
- * That is a straight violation of the rule that the Python and JS clients
- * behave identically: the Python client obviously ran, so the divergence looked
- * like a model or endpoint problem rather than a missing binary.
- *
- * Kept in its own module, with the probe injected, so the resolution order is
- * testable without spawning anything.
- */
-/** Env var that overrides everything below it. */
 export declare const PYTHON_ENV_VAR = "CAPTCHA_KRAKEN_PYTHON";
-/**
- * Candidates tried in order when nothing is configured.
- *
- * `python3` FIRST. On Debian-family systems `python` is absent; where both
- * exist they are the same interpreter in practice, and PEP 394 makes `python3`
- * the portable spelling. `python` stays as the fallback for Windows and for
- * venvs that only expose the unsuffixed name.
- */
 export declare const PYTHON_CANDIDATES: readonly ["python3", "python"];
 export interface ResolveOptions {
-    /** `config.pythonCommand`, if the caller set one. Wins outright. */
     configured?: string;
-    /** The venv interpreter, when one was found next to the CLI. Wins over probing. */
     venvPython?: string | null;
-    /** Process env, injected for testability. */
     env?: NodeJS.ProcessEnv;
-    /** Returns true if the command is runnable. Injected so tests never spawn. */
     exists?: (command: string) => boolean;
 }
-/**
- * Resolve the interpreter, most specific first:
- *
- *   1. an explicitly configured `pythonCommand`
- *   2. `CAPTCHAKRAKEN_PYTHON`
- *   3. the venv interpreter beside the bundled CLI
- *   4. the first of `python3`, `python` that actually exists
- *
- * Falls back to `python3` rather than `python` when nothing can be probed: on
- * the platform where the two differ, `python3` is the one that is present.
- */
 export declare function resolvePythonCommand(options?: ResolveOptions): string;

package/dist/python-command.js

@@ -1,46 +1,9 @@
 "use strict";
-/**
- * Which interpreter runs the bundled CaptchaKraken CLI.
- *
- * This used to be `pythonCommand = 'python'`, inline in solver.ts. On
- * Debian/Ubuntu — the most common Linux deployment target, and what CI runs —
- * there is no `python` on PATH at all, only `python3`. So every JS solve died
- * with `/bin/sh: 1: python: not found` before it ever reached the model, unless
- * a `.venv` happened to exist next to the package. The type doc claimed the
- * default was "'python' or 'python3'"; the code never tried `python3`.
- *
- * That is a straight violation of the rule that the Python and JS clients
- * behave identically: the Python client obviously ran, so the divergence looked
- * like a model or endpoint problem rather than a missing binary.
- *
- * Kept in its own module, with the probe injected, so the resolution order is
- * testable without spawning anything.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PYTHON_CANDIDATES = exports.PYTHON_ENV_VAR = void 0;
 exports.resolvePythonCommand = resolvePythonCommand;
-/** Env var that overrides everything below it. */
 exports.PYTHON_ENV_VAR = 'CAPTCHA_KRAKEN_PYTHON';
-/**
- * Candidates tried in order when nothing is configured.
- *
- * `python3` FIRST. On Debian-family systems `python` is absent; where both
- * exist they are the same interpreter in practice, and PEP 394 makes `python3`
- * the portable spelling. `python` stays as the fallback for Windows and for
- * venvs that only expose the unsuffixed name.
- */
 exports.PYTHON_CANDIDATES = ['python3', 'python'];
-/**
- * Resolve the interpreter, most specific first:
- *
- *   1. an explicitly configured `pythonCommand`
- *   2. `CAPTCHAKRAKEN_PYTHON`
- *   3. the venv interpreter beside the bundled CLI
- *   4. the first of `python3`, `python` that actually exists
- *
- * Falls back to `python3` rather than `python` when nothing can be probed: on
- * the platform where the two differ, `python3` is the one that is present.
- */
 function resolvePythonCommand(options = {}) {
     const { configured, venvPython, env = process.env, exists } = options;
     if (configured)

package/dist/selectors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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. */
+    readonly hosts: readonly string[];
+    /** On the host page: the open challenge. Detected first. */
+    readonly challenge?: readonly string[];
+    /** On the host page: the checkbox. Detected while `response` is empty and `checked` is not showing. */
+    readonly checkbox?: readonly string[];
+    /** On the host page: inline widget shapes, detected last. Iframe selectors go first; a class that lives inside the frame document (.CheckboxCaptcha, .mtcap) only ever matches an inline embed. */
+    readonly widget?: readonly string[];
+    /** On the host page: the field the vendor fills on success. Read first and unconditionally, because hCaptcha's overlay hides the anchor. */
+    readonly response?: string;
+    /** Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`. */
+    readonly checked?: 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. */
+    readonly fresh?: string;
+    /** Inside the challenge frame: the pictures a board is made of; the driver waits for each to have painted. */
+    readonly images?: readonly string[];
+    /** Inside the widget: the vendor's own submit control, tried after the generic text probes. */
+    readonly submit?: readonly string[];
+    /** Inside the challenge frame: verdict banners and what each means. */
+    readonly banners?: ReadonlyArray<readonly [string, RecaptchaBanner]>;
+    /** 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. */
+    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[];
+}
+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>;
+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 PIECE_SELECTORS: readonly string[];