captchakraken 3.0.0 → 3.2.0

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,9 @@ export declare class CaptchaKrakenSolver {
     /** Answers keyed by screenshot hash; a hit means the answer already ran and changed nothing. */
     private solutionCache;
     private repeatedAnswerSeen;
-    /** The one recording and one answer for the animated board on screen. */
+    private knownAnimated;
+    private animatedProbeDone;
+    /** The one recording for the animated board on screen, and its answer until the widget refuses it. */
     private animatedPlan;
     private keyframeMode;
     private keyframeSteadyScreens;
@@ -54,28 +60,103 @@ export declare class CaptchaKrakenSolver {
     private resampleLevel;
     /** The recording `classifyByRecording` started and left running for the branch below to finish or drop. */
     private pendingBurst;
+    /**
+     * The camera on the animated board in front of us, running across rounds until that board is gone.
+     *
+     * Distinct from `pendingBurst`, which is the speculative film one round starts and the same round spends.
+     * This one outlives a rejected answer on purpose: it is the only thing that can give the next ask a
+     * different question to answer, since the answer itself is deterministic at temperature 0.
+     */
+    private animatedFilm;
     private lastBurstFps;
     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;
@@ -96,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
@@ -110,6 +193,13 @@ export declare class CaptchaKrakenSolver {
     /** The `--model` argv, or nothing: without VLLM_BASE_URL the CLI can see a credentials file this process cannot. */
     private modelName;
     private resolveCli;
+    /** What is LEFT of the solve, as a bound on one ask.
+     *
+     * The CLI is a child process and the solve deadline is only read between steps, so nothing stops an
+     * ask already in flight — measured against the hosted endpoint, one hung for ~124s inside a 45s
+     * budget and the attempt ran 143s. Never below the floor: a keyframe ask carries six images, and a
+     * timeout shorter than the work turns a busy endpoint into a guaranteed failure. */
+    private askTimeoutMs;
     /** One-shot CLI tool call; `{}` on any failure so polling callers keep going. */
     private runCliTool;
     /** Start the persistent CV worker once; false when it cannot start, so callers fall back to one-shot spawns. */
@@ -142,17 +232,27 @@ export declare class CaptchaKrakenSolver {
     private waitForAnyClickedTileLoaded;
     /** Click, watch the clicked tiles, re-solve while they swap, submit on `done` or a chipped board. */
     private solveRecaptchaGrid;
-    private recordKeyframeBurst;
     /**
      * Start filming now and decide later what it was for: the classifier, the speculative film, or the
      * recording an animated answer is sliced from. Every window is wall-clock. A cycle is a screen that
      * comes back; a board that shows nothing new for a floor window has settled. There is deliberately no
      * "enough screens, stop" exit: measured on number_with_highest_value_video it failed every seed either way.
+     *
+     * `continuous` keeps the camera rolling past the first answer, for the whole solve. A one-shot burst can
+     * only ever show the model the screens that happened to fall inside its window — measured, a 4s burst
+     * against a 5.3s cycle showed two screens of three, and when the answer lived on the third there was no
+     * second chance, because the reused answer is identical by construction. Filming on means every later
+     * round slices a STRICTLY LONGER film: more repetitions for `_detect_cycle` to confirm against, and, on a
+     * board that never repeats, six evenly-spread picks across the whole solve instead of across four seconds.
+     *
+     * Longer, but never of TWO boards. A vendor that deals a fresh puzzle on a miss has replaced everything
+     * filmed so far, and keyframes cut across both states describe neither. `resume` cuts the film where our
+     * answer landed; a screen from before the cut coming back is what un-cuts it. See `snapshot`.
      */
     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;
@@ -163,15 +263,28 @@ export declare class CaptchaKrakenSolver {
     private resetSolveState;
     /** Keyed on the retry mode too: the missed-tiles answer legitimately overlaps the previous one. */
     private static answerSignature;
+    /** The recording still stands; dropping only the refused answer makes the retry an inference, not a burst. */
+    private invalidateAnimatedAnswer;
     /** True when this answer already ran and changed nothing: resample, and let the recording path have a go. */
     private noteAnswer;
     /** A cache hit costs no inference, and means the answer already ran: the board cycles. */
     private answerFor;
+    /**
+     * Drop the ANSWER, keep the camera.
+     *
+     * The two are deliberately separable. An answer the widget refused is spent — reusing it just presses the
+     * same wrong thing until the no-progress fence trips, three rounds in, with half the budget unspent. The
+     * film is the opposite: every second it keeps running makes the next slice a better question. So a
+     * refusal discards this and leaves `animatedFilm` alone; only a board that is GONE stops the camera.
+     */
     private discardAnimatedPlan;
+    /** The board is gone: its film can never describe the next one, so end it and free the frames. */
+    private stopAnimatedFilm;
     /** Static or animated, decided by filming once. The film stays running for the branch that uses it. */
     private classifyByRecording;
     private releasePendingBurst;
     private shouldSpeculate;
+    /** One second look per solve: a repeated answer arms it, and the recording it takes spends it. */
     private shouldRetryAsAnimated;
     private getSolution;
     /** One inference through the CLI. */