captchakraken 2.1.0

package/dist/solver.d.ts

@@ -0,0 +1,264 @@
+import { PlaywrightPage as Page, PlaywrightElementHandle as ElementHandle } from './playwright-types';
+import { CaptchaKrakenConfig, SolveResult } from './types';
+export declare class CaptchaKrakenSolver {
+    private config;
+    private lastMousePosition;
+    private imageCounter;
+    private sessionDebugDir;
+    private stepIndex;
+    private solveStartMs;
+    private gridDebugDir;
+    private gridDebugSeq;
+    private cvWorker;
+    private cvWorkerReady;
+    private cvWorkerSeq;
+    private cvWorkerPending;
+    private cvWorkerBuf;
+    private solutionCache;
+    constructor(config?: CaptchaKrakenConfig);
+    solve(page: Page): Promise<SolveResult | void>;
+    private solveImpl;
+    /**
+     * Fire the optional onStep observer with a fresh screenshot of the captcha
+     * element. No-op (beyond a cheap early return) when no callback is set, so it
+     * stays off the critical path in normal runs. The emitted PNG is owned by the
+     * callback — we never delete it. Best-effort: a screenshot or callback error
+     * never fails the solve.
+     */
+    private emitStep;
+    private solveSingle;
+    private getVerifyButton;
+    private hasNonEmptyFieldValue;
+    /**
+     * Detect reCAPTCHA's "Please select all matching images" error banner
+     * (and the related "Please try again" / "Please also check the new images"
+     * variants). These appear in the bframe AFTER clicking Verify with an
+     * incomplete selection. The tiles do NOT refresh on this error — without
+     * special handling the LoRA sees the same image, returns "done" (because
+     * to it everything matching IS selected), we click Verify again, and we
+     * loop until the session times out. We use this signal to switch the next
+     * grid call into "missed-tiles" retry mode.
+     */
+    private hasRecaptchaUnderselectError;
+    private isRecaptchaAnchorChecked;
+    private isHcaptchaAnchorChecked;
+    /**
+     * True the moment the vendor reports the whole captcha solved — the anchor
+     * checkbox flipped to checked, or the response token got populated. This is a
+     * definitive "done" signal that a lingering, animating-closed challenge frame
+     * is not: after the final submit, hCaptcha keeps the challenge iframe VISIBLE
+     * for a couple of seconds while it verifies, so treating that frame as a fresh
+     * puzzle (the old behavior) burned ~18s re-running the pipeline on it.
+     */
+    private isCaptchaSolved;
+    /**
+     * True when an image challenge is open AND has actually rendered its prompt —
+     * i.e. a fresh round we should solve, as opposed to a frame animating closed
+     * (whose prompt has already gone). Used to tell "next round" from "solved,
+     * closing" after a submit without waiting out a fixed timeout.
+     */
+    private isChallengeFreshlyRendered;
+    /**
+     * Block until the hCaptcha challenge frame's task images have actually
+     * painted, so we don't screenshot a blank/half-loaded grid.
+     *
+     * hCaptcha renders each grid tile as a `.task-image .image` div whose
+     * `background-image` is set once the asset loads; the prompt sits in
+     * `.prompt-text`. Image-select (click/drag) challenges use a single
+     * `.challenge-example` / `canvas` surface instead. We wait for either family
+     * to be present AND for the background-image URLs to be populated (not the
+     * empty `url("")` placeholder hCaptcha ships before the asset arrives).
+     *
+     * Best-effort: a timeout or a missing content frame just falls through to the
+     * screenshot rather than throwing — the existing fail-fast path still covers a
+     * genuinely unsupported puzzle.
+     */
+    private waitForHcaptchaChallengeImages;
+    /**
+     * Stage-1 detection: is an *interactive* captcha widget present in the DOM at
+     * all — even if its iframe hasn't finished rendering yet?
+     *
+     * This is deliberately broader than detectCaptcha (which only returns a
+     * VISIBLE, not-yet-solved element). We use it to distinguish two cases that
+     * detectCaptcha() === null cannot tell apart:
+     *
+     *   - A reCAPTCHA-v2 / hCaptcha widget IS in the DOM but is still loading
+     *     (iframe present, glyph not painted) → we should WAIT for it.
+     *   - There is no interactive widget — reCAPTCHA v3 (score-based, invisible)
+     *     or an hCaptcha that only triggers on a user action → we must FAIL FAST.
+     *
+     * reCAPTCHA v3 injects only `iframe[src*="recaptcha/api2/anchor"]` with
+     * `size=invisible` in the src, and never an `api2/bframe` challenge frame, so
+     * we exclude the invisible variant here.
+     */
+    hasInteractiveWidgetInDom(page: Page): Promise<boolean>;
+    detectCaptcha(page: Page): Promise<ElementHandle | null>;
+    /**
+     * Initialize a fresh dump directory for one reCAPTCHA 3x3 dynamic-driver
+     * session. Frames + a state.jsonl log land here so the click/fade/wait timing
+     * can be replayed offline. Gated on CAPTCHA_DEBUG=1 — the per-frame dumps and
+     * extra state queries add latency, so they stay off in normal runs. Set
+     * CAPTCHA_DEBUG=1 to capture them when diagnosing timing. Best-effort.
+     */
+    private initGridDebug;
+    /**
+     * Log a structured event for the grid driver: prints a one-line summary to the
+     * console and appends a JSON record to state.jsonl. If `framePath` is given,
+     * copies that frame into the dump dir under a sequenced, labeled name so the
+     * record can be matched to the exact pixels the detector saw. Best-effort.
+     */
+    private gridDebug;
+    private saveImageForDebug;
+    private archiveLatestDebugRun;
+    /**
+     * Resolve the bundled CaptchaKraken CLI root and the python interpreter to
+     * run it with. Prefers the packaged venv python (postinstall bootstrap),
+     * falling back to the configured/`python` command. Throws if the CLI folder
+     * is missing — callers that must not throw (e.g. runCliTool) wrap this.
+     */
+    private resolveCli;
+    /**
+     * Run an OpenCV tool subcommand of the CLI (e.g. `grid-cell-states a.png
+     * b.png`) and return its parsed single-line JSON. These subcommands print
+     * exactly one JSON object on stdout (timing records go to stderr), so we
+     * parse the whole trimmed stdout. Best-effort: returns `{}` on any failure so
+     * polling callers can treat it as "inconclusive, keep going" without throwing.
+     */
+    private runCliTool;
+    /**
+     * Lazily start the persistent CV worker (`python -m captchakraken.cli serve`) and resolve
+     * once it has imported cv2/numpy and emitted its `{"ready":true}` handshake.
+     * Returns false if it can't be started (caller then falls back to one-shot
+     * subprocesses). Idempotent: subsequent calls await the same readiness promise.
+     */
+    private ensureCvWorker;
+    /** Send one request to the CV worker and await its JSON result. Throws on any
+     *  worker failure so callers can fall back to the one-shot path. */
+    private cvWorkerRequest;
+    /** Kill the worker and clear state. Safe to call repeatedly. */
+    private teardownCvWorker;
+    /**
+     * Run a CV tool through the persistent worker when available, falling back to a
+     * one-shot `runCliTool` subprocess otherwise. `cmd`/`payload` map to the
+     * worker's protocol; `fallbackArgs` is the equivalent one-shot argv. Worker
+     * results are wrapped to match the one-shot JSON shape:
+     *   - grid-cell-states[-fixed]: worker returns the states object directly, or
+     *     {grid:null}; the one-shot returns the same shape, so just pass through.
+     *   - find-grid: worker returns the array (or null) as `result`.
+     * Best-effort: never throws.
+     */
+    private runCvTool;
+    /**
+     * Block until a reCAPTCHA grid's cells have settled — none blank, none
+     * mid-fade — before we screenshot it for the model. reCAPTCHA fades new tiles
+     * in over ~1s; capturing mid-fade feeds the LoRA a blank/partial grid.
+     *
+     * We poll: screenshot the challenge element, keep the last two frames, and ask
+     * the CLI's batched `grid-cell-states` (one subprocess per poll) which cells
+     * are empty/changing/loaded. We return as soon as every cell is loaded, or on
+     * timeout. Best-effort, mirroring `waitForHcaptchaChallengeImages`: never
+     * throws, and falls through on timeout so a stuck/odd grid still proceeds to
+     * the normal screenshot path. Temp frames are always cleaned up.
+     */
+    private waitForGridCellsLoaded;
+    /**
+     * Read a PNG's pixel dimensions from its IHDR chunk (bytes 16-23, big-endian).
+     * Avoids pulling in an image-size dependency. Returns null if the file isn't a
+     * readable PNG.
+     */
+    private readPngDimensions;
+    /**
+     * Detect the reCAPTCHA grid once for a puzzle session: screenshot the element,
+     * run `find-grid`, and read the screenshot's pixel dimensions. Grid boxes are
+     * pixel coords in SCREENSHOT space (not page CSS space). Returns null if no
+     * grid is detected. The geometry is stable across the in-place dynamic refresh
+     * (only tile images change), so callers cache the result for the session.
+     */
+    private getGridBoxes;
+    /**
+     * Map a model-returned normalized bbox (fractions of the element/screenshot)
+     * to a 1-indexed grid cell. Uses the bbox center, converts to screenshot
+     * pixels, and returns the cell whose pixel box contains it. Cell numbering is
+     * row-major (matches the CLI's find_grid output). Returns null if the center
+     * falls outside every cell (e.g. in a gutter) — callers click the raw bbox
+     * anyway and skip per-tile tracking.
+     */
+    private bboxToCell;
+    /**
+     * Center of a 1-indexed grid cell in PAGE pixel space, for mouse moves.
+     * Converts the cached screenshot-pixel box to page coords via the session's
+     * scaleX/scaleY (screenshot px -> page px) and element origin.
+     */
+    private cellCenterPage;
+    /** Smooth-move the mouse over one cell's center with intra-cell jitter. */
+    private hoverCell;
+    /**
+     * Query per-cell grid state using the SESSION'S CACHED grid boxes via the
+     * `grid-cell-states-fixed` CLI command. This is critical: the dynamic refresh
+     * blanks tiles to near-white, which makes find_grid fail on that frame, so the
+     * self-detecting `grid-cell-states` would return {grid:null} mid-fade and a
+     * naive caller would misread that as "nothing loading / solved". Passing the
+     * cached boxes keeps empty/changing/selected correct even while tiles are
+     * blank. Returns null only on a genuine CLI failure. Best-effort.
+     */
+    private gridCellStates;
+    /** Order a loading set so `priority` cells (just-clicked) come first. */
+    private orderByPriority;
+    /**
+     * Detect whether any tiles are blank or fading, watching for the ONSET of the
+     * reCAPTCHA refresh over a short grace window. The blank/fade transition lags
+     * the click by a beat, so a single snapshot right after clicking misses it
+     * (the tile still shows its old image — not yet white, not yet changing). We
+     * poll consecutive frames and mark a cell loading if it is `empty` (≥97%
+     * near-white) OR `changing` (>2% pixels differ). HOVERS a clicked tile each
+     * poll so the mouse keeps moving (no unnatural pauses). Returns the loading
+     * cells (priority/clicked first) as soon as any appears, or [] if the whole
+     * window passes with nothing loading (→ solved). Logs every poll + frame.
+     */
+    private currentLoadingCells;
+    /**
+     * After loading is detected, wait until at least one of the given blank/fading
+     * cells reaches the `loaded` state, HOVERING those cells (in order) the whole
+     * time so the mouse never sits still. Returns true once a tile loads, false on
+     * timeout (caller proceeds anyway). Uses the session's cached grid boxes so it
+     * works while tiles are blank. Logs every poll + frame.
+     */
+    private waitForAnyClickedTileLoaded;
+    /**
+     * Multi-round driver for reCAPTCHA 3x3 dynamic puzzles ("click all X" where
+     * tiles refresh in place). One invocation = one puzzle session.
+     *
+     * The CLI is authoritative about WHAT to do — it runs the blue-badge detector,
+     * filters out already-selected and still-loading tiles, and returns one of:
+     *   - `click`: click these tiles (already filtered to fresh, ready tiles)
+     *   - `wait` : nothing to click yet, tiles are still loading — do NOT submit
+     *   - `done` : nothing matching remains — submit (click Verify)
+     *
+     * This driver owns the HUMAN-LIKE WAITING the CLI can't: after a click round,
+     * and on a `wait`, it hovers the just-clicked / currently blank+fading tiles
+     * (in click order) and waits for at least one to finish reloading before
+     * re-screenshotting and re-solving — so we don't burn a solver call on a grid
+     * that's still mid-fade. It submits only on `done`.
+     *
+     * Returns the same shape as solveSingle so the outer solve loop — including the
+     * under-selection retry and post-solve detectCaptcha — wraps it unchanged.
+     */
+    private solveRecaptchaGrid;
+    private getSolution;
+    /**
+     * Run `fn` (typically the model query) while idly drifting the cursor over
+     * the captcha, so the mouse behaves like a human weighing the options instead
+     * of freezing during inference. Uses the same cursory-ts trajectories as real
+     * clicks; cancelled the instant `fn` resolves. Best-effort — any wander error
+     * is swallowed and never fails the solve. Disable via config.idleMouseWander.
+     */
+    private withIdleWander;
+    move(page: Page, selectorOrElement: string | ElementHandle, options?: {
+        paddingPercentage?: number;
+    }): Promise<void>;
+    moveAndClick(page: Page, element: ElementHandle): Promise<void>;
+    private performSmoothMove;
+    private tracePath;
+    private executeClick;
+    private executeDrag;
+}