captchakraken 2.3.0 → 2.6.0

package/dist/model-name.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBundledCliRoot = getBundledCliRoot;
+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))
+        return bundled;
+    return node_path_1.default.resolve(__dirname, '..', '..', 'python');
+}
+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 } = {}) {
+    if (env.CAPTCHA_LORA_NAME)
+        return env.CAPTCHA_LORA_NAME;
+    try {
+        const reg = readJson(cliRoot, 'models.json');
+        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

@@ -59,6 +59,13 @@ export interface PlaywrightElementHandle {
     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>;
 }
 /**
  * Structural subset of Playwright's `Frame` (an iframe's content document).
@@ -96,6 +103,19 @@ 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.
+     */
+    keyboard: {
+        type(text: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+        press(key: string, options?: {
+            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). */
@@ -109,6 +129,14 @@ export interface PlaywrightPage {
     $(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>;
 }

package/dist/puppeteer-adapter.d.ts

@@ -14,6 +14,7 @@
  *   - `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.
@@ -42,6 +43,7 @@ interface PuppeteerElementHandle {
     scrollIntoView(): Promise<void>;
     isVisible(): Promise<boolean>;
     evaluate(pageFunction: (el: any, ...args: any[]) => any, ...args: any[]): Promise<any>;
+    $(selector: string): Promise<PuppeteerElementHandle | null>;
 }
 interface PuppeteerFrame {
     $(selector: string): Promise<PuppeteerElementHandle | null>;
@@ -56,11 +58,20 @@ interface PuppeteerPage {
         down(options?: any): Promise<void>;
         up(options?: any): Promise<void>;
     };
+    keyboard: {
+        type(text: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+        press(key: string, options?: any): Promise<void>;
+        down(key: string, options?: any): Promise<void>;
+        up(key: string): Promise<void>;
+    };
     waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
     viewport(): ViewportSize | null;
     $(selector: string): Promise<PuppeteerElementHandle | null>;
     $$(selector: string): Promise<PuppeteerElementHandle[]>;
     $eval(selector: string, pageFunction: (element: Element) => any, ...args: any[]): Promise<any>;
+    isClosed(): boolean;
 }
 /**
  * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright

package/dist/puppeteer-adapter.js

@@ -15,6 +15,7 @@
  *   - `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.
@@ -62,6 +63,7 @@ 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)),
     };
 }
 function wrapFrame(f) {
@@ -86,11 +88,32 @@ function fromPuppeteer(page) {
             down: (options) => page.mouse.down(options),
             up: (options) => page.mouse.up(options),
         },
+        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.
+            press: async (key) => {
+                const parts = key.split('+');
+                const target = parts.pop();
+                for (const mod of parts)
+                    await page.keyboard.down(mod);
+                await page.keyboard.press(target);
+                for (const mod of parts.reverse())
+                    await page.keyboard.up(mod);
+            },
+        },
         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.
+        isClosed: () => page.isClosed(),
     };
 }

package/dist/python-command.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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

@@ -0,0 +1,60 @@
+"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)
+        return configured;
+    const fromEnv = env[exports.PYTHON_ENV_VAR];
+    if (fromEnv)
+        return fromEnv;
+    if (venvPython)
+        return venvPython;
+    if (exists) {
+        for (const candidate of exports.PYTHON_CANDIDATES) {
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return exports.PYTHON_CANDIDATES[0];
+}

package/dist/slide-geometry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The algebra behind a puzzle-piece slider's closed loop.
+ *
+ * Split out of solver.ts because it is the one part of this feature that is
+ * pure arithmetic, duplicated across the two ports, and impossible to notice
+ * drifting: a wrong ratio here does not throw, it just releases the piece in the
+ * wrong place, and the puzzle fails the way an unsolved puzzle fails. Keeping it
+ * dependency-free means it can be unit-tested with `node --test` alongside
+ * limits.ts, against the same cases as
+ * `PageSolver._solve_slide_geometry` in the Python port.
+ */
+/**
+ * Piece width and handle-to-piece travel ratio, from probe measurements.
+ *
+ * Each measurement is `[handle offset, width of what changed]`, where the width
+ * spans the piece's ORIGINAL left edge to its CURRENT right edge — so
+ * `width = pieceWidth + ratio x offset`. Two of them determine both unknowns.
+ *
+ * With only one usable measurement the system is underdetermined, so `ratio` is
+ * ASSUMED to be 1 — true of every vendor observed, and the assumption is stated
+ * here rather than buried as a default. A ratio solved from implausible
+ * measurements (a redraw, a piece that hit the wall between probes) is rejected
+ * the same way: better a 1:1 guess that overshoots and gets corrected than a
+ * ratio of 0.02 that sends the handle off the track and, under camoufox, into a
+ * mouse move that never returns.
+ *
+ * `pieceWidth: null` means "could not measure" — the caller falls back to
+ * steering by the handle's own travel.
+ */
+export declare function solveSlideGeometry(widths: Array<[number, number]>, widgetWidth: number): {
+    pieceWidth: number | null;
+    ratio: number;
+};

package/dist/slide-geometry.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * The algebra behind a puzzle-piece slider's closed loop.
+ *
+ * Split out of solver.ts because it is the one part of this feature that is
+ * pure arithmetic, duplicated across the two ports, and impossible to notice
+ * drifting: a wrong ratio here does not throw, it just releases the piece in the
+ * wrong place, and the puzzle fails the way an unsolved puzzle fails. Keeping it
+ * dependency-free means it can be unit-tested with `node --test` alongside
+ * limits.ts, against the same cases as
+ * `PageSolver._solve_slide_geometry` in the Python port.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.solveSlideGeometry = solveSlideGeometry;
+/**
+ * Piece width and handle-to-piece travel ratio, from probe measurements.
+ *
+ * Each measurement is `[handle offset, width of what changed]`, where the width
+ * spans the piece's ORIGINAL left edge to its CURRENT right edge — so
+ * `width = pieceWidth + ratio x offset`. Two of them determine both unknowns.
+ *
+ * With only one usable measurement the system is underdetermined, so `ratio` is
+ * ASSUMED to be 1 — true of every vendor observed, and the assumption is stated
+ * here rather than buried as a default. A ratio solved from implausible
+ * measurements (a redraw, a piece that hit the wall between probes) is rejected
+ * the same way: better a 1:1 guess that overshoots and gets corrected than a
+ * ratio of 0.02 that sends the handle off the track and, under camoufox, into a
+ * mouse move that never returns.
+ *
+ * `pieceWidth: null` means "could not measure" — the caller falls back to
+ * steering by the handle's own travel.
+ */
+function solveSlideGeometry(widths, widgetWidth) {
+    if (!widths.length)
+        return { pieceWidth: null, ratio: 1 };
+    let ratio = 1;
+    let pieceWidth = null;
+    if (widths.length >= 2) {
+        const [o1, w1] = widths[0];
+        const [o2, w2] = widths[widths.length - 1];
+        if (o2 !== o1) {
+            const candidate = (w2 - w1) / (o2 - o1);
+            if (candidate >= MIN_RATIO && candidate <= MAX_RATIO) {
+                ratio = candidate;
+                pieceWidth = w1 - ratio * o1;
+            }
+        }
+    }
+    if (pieceWidth === null) {
+        const [o, w] = widths[widths.length - 1];
+        pieceWidth = w - ratio * o;
+    }
+    // A piece narrower than a few pixels, or wider than half the widget, is a
+    // measurement of something else — a wholesale redraw, a fade, a spinner.
+    if (pieceWidth < MIN_PIECE_PX || pieceWidth > widgetWidth * MAX_PIECE_FRACTION) {
+        return { pieceWidth: null, ratio };
+    }
+    return { pieceWidth, ratio };
+}
+// Keep these identical to the literals in page_solver.py::_solve_slide_geometry.
+const MIN_RATIO = 0.2;
+const MAX_RATIO = 3.0;
+const MIN_PIECE_PX = 3.0;
+const MAX_PIECE_FRACTION = 0.6;