captchakraken 2.3.0 → 2.6.0

package/dist/solver.d.ts

@@ -1,5 +1,18 @@
 import { PlaywrightPage as Page, PlaywrightElementHandle as ElementHandle } from './playwright-types';
+import { CaptchaWatcher, WatchOptions } from './watcher';
 import { CaptchaKrakenConfig, SolveResult } from './types';
+/**
+ * The two numbers that bound a solve, together, because they only make sense
+ * together: `maxSolveLoops` is the count that FITS inside the timeout at the
+ * ~4-7s a round costs, and the timeout is the backstop for when it does not.
+ * Named rather than inlined as `??` defaults so the relationship between them
+ * can be pinned by a test — see no-progress.test.ts. The Python port keeps the
+ * same pair on `PageSolverConfig`.
+ */
+export declare const SOLVE_DEFAULTS: {
+    readonly maxSolveLoops: 6;
+    readonly overallSolveTimeoutMs: 45000;
+};
 export declare class CaptchaKrakenSolver {
     private config;
     private lastMousePosition;
@@ -15,11 +28,34 @@ export declare class CaptchaKrakenSolver {
     private cvWorkerPending;
     private cvWorkerBuf;
     private solutionCache;
+    private repeatedAnswerSeen;
+    private keyframeMode;
+    private lastAnswerSig;
+    private noProgressRounds;
     private state;
     private lastSubmitFrameHash;
     private solveSessionId;
     constructor(config?: CaptchaKrakenConfig);
     solve(page: Page): Promise<SolveResult | void>;
+    /**
+     * Install an auto-solver: probe `page` on a timer and solve any captcha that
+     * becomes visible, until `stop()`.
+     *
+     * Returns immediately — the watching happens in the background, so your
+     * automation carries on and captchas are handled underneath it.
+     *
+     * Nothing is injected into the page on any platform; see watcher.ts for why,
+     * and for the note on Camoufox, where the probe's DOM reads land in its
+     * isolated world by default.
+     *
+     * ```typescript
+     * const solver = new CaptchaKrakenSolver();
+     * const watcher = solver.watch(page);
+     * await page.goto('https://example.com/protected');   // solved as it appears
+     * await watcher.stop();
+     * ```
+     */
+    watch(page: Page, options?: WatchOptions): CaptchaWatcher;
     private solveImpl;
     /**
      * Fire the optional onStep observer with a fresh screenshot of the captcha
@@ -208,17 +244,37 @@ export declare class CaptchaKrakenSolver {
     /** 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.
+     * Watch the just-clicked tiles until the widget says what it did with them.
+     *
+     * Two answers because reCAPTCHA gives a click one of exactly two replies, and
+     * they are the two kinds of board:
+     *
+     *   - `chipped`: the small blue chip landed in the tiles' top-left corners —
+     *     the photos were KEPT. Nothing is on its way in, the selection is the
+     *     answer, and the caller should press Verify.
+     *   - `loading`: the photos are blanking or dissolving under a large centred
+     *     check — those tiles are being SWAPPED, and what lands may match too, so
+     *     the board has to be read again.
+     *
+     * A widget that swaps one clicked cell swaps them all, so the two never share
+     * a board and one look at the tiles we just clicked settles it. The chip is
+     * what the CV layer reports as `selected` (top-left corner only, behind a
+     * circularity and a centroid test a centred check fails), and we already read
+     * it on every poll. `chipped` needs EVERY watched tile: a partial reading is a
+     * misread, and calling a swapping board finished submits half an answer and
+     * burns the attempt, where calling a chipped board unfinished costs one
+     * inference.
+     *
+     * 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 as soon as either verdict is in, or `{loading: [], chipped: false}`
+     * if the whole window passes with nothing happening (→ solved). Logs every
+     * poll + frame.
      */
-    private currentLoadingCells;
+    private watchClickedTiles;
     /**
      * 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
@@ -241,13 +297,124 @@ export declare class CaptchaKrakenSolver {
      * 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`.
+     * that's still mid-fade.
+     *
+     * Only a board that SWAPS a clicked tile out is worth those extra rounds. One
+     * that ticks the tile and keeps the photo has been fully answered by the round
+     * that clicked it — same as the 4x4 — so `watchClickedTiles` reports the chip
+     * and this submits there and then. Rounds 2..N exist for the fading board and
+     * nothing else. It submits on `done`, and on a board that ticked our clicks.
      *
      * 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;
+    /**
+     * Record the animated challenge and return the directory holding the burst.
+     *
+     * The driver owns the browser, so it does the recording; the CLI does the
+     * slicing (`solve-animated`). One zero-padded PNG per frame, because the slicer
+     * sorts by name and reads the clip's temporal structure — `frame_9.png` sorting
+     * after `frame_10.png` would shuffle the burst and turn a detectable cycle into
+     * noise.
+     *
+     * Geometry comes from config and defaults to the collector's (4s @ 10fps), so a
+     * challenge recorded here is the same shape of artifact the model trained on.
+     * The caller must remove the directory when the actions are done with — the
+     * keyframes the wait gate re-reads on every poll live inside it.
+     */
+    private recordKeyframeBurst;
+    /**
+     * Slice a recorded burst into keyframes and solve them in ONE model request.
+     *
+     * Deliberately not routed through `solveFrameFreshnessGuarded`. That guard
+     * re-solves when the frame changes during inference, and an animated challenge
+     * changes by definition — every attempt would be judged stale and the whole
+     * re-solve budget would burn without ever acting. The `frame` in the answer is
+     * the real guard: it names the state to act in, and `waitForKeyframe` enforces it.
+     *
+     * Also not deduped by screenshot hash: there is no single screenshot, and two
+     * recordings of the same widget are never byte-identical anyway.
+     */
+    private getAnimatedSolution;
+    /**
+     * Hold until the widget looks like `keyframePath` around the 0–1 point (cx, cy).
+     *
+     * This is the reason an animated answer names a frame. The model picked the
+     * moment its target was visible, and the coordinates are only correct at that
+     * moment; clicking as soon as the answer arrives lands on whatever the sprite
+     * happens to be doing, which for a cross-fade is usually background.
+     *
+     * Only the neighbourhood of the action point is compared, with the same box and
+     * metric the training label's frame was chosen with. Local rather than
+     * whole-frame because everything ELSE in these puzzles is also moving: a
+     * whole-frame match would need every unrelated sprite to align too, and would
+     * essentially never open.
+     *
+     * Never throws. Returns whether the state was reached; on timeout the caller
+     * clicks anyway (see `keyframeWaitTimeoutMs`).
+     *
+     * NOT ATTEMPTED on an `even` clip. The slicer picks that mode precisely when
+     * the clip never revisits a picture it has already shown — a rotation, a
+     * one-way fade, a sprite crossing — so there is no state to come back to and
+     * this can only run out its full 6s, PER CLICK, before clicking the
+     * coordinates it already had. It is also the normal case, not a corner: all
+     * 116 real clips under cleanSamples/test/raw are `even` and `cycle` has never
+     * fired on real footage. Measured on hcaptcha_rotating_obj_video: 6.0s of a
+     * 28.8s solve, closest region diff 0.0721 against a 0.05 tolerance, then the
+     * same click, then solved. Kept for `cycle`/`static`, where the state does
+     * come back and waiting is the difference between the sprite and background.
+     */
+    private waitForKeyframe;
+    /**
+     * Per-solve state that must not leak into the next challenge on the page.
+     *
+     * A repeat is a fact about ONE challenge. Carrying it forward would make the
+     * captcha after a cycling one record a burst it does not need.
+     */
+    private resetSolveState;
+    /**
+     * A stable identity for "the answer this round is about to execute".
+     *
+     * Keyed on the retry mode too: the missed-tiles retry deliberately re-asks
+     * about the same board and its answer legitimately overlaps the previous one,
+     * so counting that as a repeat would abandon the one path built to recover
+     * from an under-selection.
+     *
+     * Coordinates are ROUNDED rather than compared exactly — the same tile chosen
+     * twice can differ in the last float digit after the normalise/clamp
+     * round-trip, and a repeat that reads as "different" is a repeat that costs a
+     * round. Returns null when the answer cannot be summarised, which counts as
+     * "not a repeat": an unreadable answer must never be why a solve is
+     * abandoned. Mirrors page_solver.py `_answer_signature`.
+     */
+    private static answerSignature;
+    /** Count consecutive identical answers; see `maxNoProgressRounds`. */
+    private noteAnswer;
+    /**
+     * The answer for this picture, asking the model only if we have not already.
+     *
+     * The cache saving is real and is kept: a byte-identical picture costs no
+     * second inference. What changed is what a hit MEANS. It used to mean
+     * "nothing has changed, so this answer still stands"; it actually means the
+     * answer already ran and moved nothing, because every answer this returns is
+     * executed. So the hit is served (it is free) and recorded, and the round
+     * after it stops guessing at a still frame — see `shouldRetryAsAnimated`.
+     */
+    private answerFor;
+    /**
+     * Should this round be recorded and solved from keyframes instead of read as
+     * a still?
+     *
+     * reCAPTCHA is excluded deliberately. Its dynamic 3x3 REPLACES tiles in place
+     * and has its own multi-round driver with its own fade gates; its grids are
+     * never animated, so escalating there would swap a path that works for one
+     * that cannot read a grid.
+     */
+    private shouldRetryAsAnimated;
     private getSolution;
+    /** One inference: build the CLI invocation, run it, parse what comes back. */
+    private askModel;
     /**
      * Query the model for `initialShot`, then guard against the captcha frame
      * having changed DURING inference. reCAPTCHA/hCaptcha fade fresh tiles in over
@@ -315,7 +482,7 @@ export declare class CaptchaKrakenSolver {
     /**
      * 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
+     * of freezing during inference. Uses the same generate_trajectory paths as real
      * clicks; cancelled the instant `fn` resolves. Best-effort — any wander error
      * is swallowed and never fails the solve. Disable via config.idleMouseWander.
      */
@@ -328,4 +495,39 @@ export declare class CaptchaKrakenSolver {
     private tracePath;
     private executeClick;
     private executeDrag;
+    /**
+     * First VISIBLE match for `selectors`, tried in order.
+     *
+     * `scope` is the challenge frame, or — for the vendors that render into the
+     * host page rather than an iframe — the widget element itself. Never the
+     * page: the generic tail of both selector tables would otherwise happily
+     * match a login form's text box or a carousel's drag handle somewhere else on
+     * the document, and the answer would go there.
+     */
+    private findControl;
+    /** Put the model's reading of a distorted-text captcha into its box. */
+    private executeType;
+    /** `captchakraken track-piece` — box of what moved, handle masked out. */
+    private trackPiece;
+    /**
+     * Drive a puzzle-piece slider until the PIECE reaches the model's slot.
+     *
+     * The model is asked for one thing here — the centre of the gap — because it
+     * is the only thing the picture can tell it. What it cannot know is how far
+     * the handle must travel to put the piece there: the handle is elsewhere on
+     * the widget, and the ratio between the two is a vendor implementation detail
+     * that several of them deliberately vary.
+     *
+     * So this is closed-loop, not a calculation. Press the handle, nudge it twice
+     * by known amounts, and watch the screen: union(before, after) spans the
+     * piece's ORIGINAL left edge to its CURRENT right edge, so its width is
+     * pieceWidth + ratio x nudge. Two nudges, two widths, two unknowns — solve for
+     * both, then steer the remaining distance and re-measure. The mouse is not
+     * released until the piece is home, because on every one of these puzzles
+     * releasing IS the submit; there is no Verify button to reconsider at.
+     *
+     * Returns false if there is nothing here to drag, leaving the caller's normal
+     * no-op handling to deal with it.
+     */
+    private executeSlide;
 }