captchakraken 2.9.0 → 3.1.0

package/dist/solver.d.ts

@@ -1,834 +1,257 @@
-import { PlaywrightPage as Page, PlaywrightElementHandle as ElementHandle } from './playwright-types';
+/**
+ * Browser page driver. Finds the widget, photographs it, asks the bundled Python engine what to do,
+ * and performs the answer. Mirrors python/src/captchakraken/page_solver.py.
+ */
+import { PlaywrightPage as Page, PlaywrightElementHandle as ElementHandle, PlaywrightLocator as Locator } from './playwright-types';
 import { CaptchaWatcher, WatchOptions } from './watcher';
 import { PhaseBudget } from './timing';
 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`.
- */
-/**
- * Does this answer need the widget's box to be performed?
- *
- * Only a coordinate-bearing action does. `done` means "nothing left to click"
- * and is the answer a vendor that closes on success will be showing no widget
- * for, so requiring a box for it fails the solve at the moment it succeeded.
- *
- * Written as an ALLOW-LIST of what needs nothing rather than a list of what
- * does: a new coordinate action added later must default to needing the box,
- * because that is the direction where being wrong throws instead of clicking
- * nowhere.
- */
+import { FrameRole, Vendor } from './kinds';
+/** What detection found: the handle to photograph, the locator to search inside, and which table entry named it. */
+export interface Widget {
+    el: ElementHandle;
+    at: Locator;
+    vendor: Vendor;
+    role: FrameRole;
+}
+/** An allow-list of what needs nothing: the other direction raises instead of clicking at the origin. */
 export declare function answerNeedsElementBox(actions: ReadonlyArray<{
     action?: string;
 }>): boolean;
-/**
- * Is this the challenge TRANSITIONING under us, rather than a dead puzzle?
- *
- * hCaptcha swaps in the next round while we hold the old iframe, so a
- * screenshot on it fails "not visible" / "Timeout" / "not attached". GeeTest
- * does the mirror image: it CLOSES the panel the moment it accepts an answer,
- * so the widget we are holding loses its layout box between the screenshot and
- * the click. Both are the widget moving on, and the answer to both is to
- * re-detect on the next round rather than to fail the solve.
- *
- * The caller gates this on having ALREADY INTERACTED, which is what keeps it
- * honest: a first-frame failure is a genuine problem and still surfaces.
- *
- * Measured 2026-09-07 on gt4.geetest.com — every live GeeTest attempt ended
- * "Could not get bounding box of captcha element" on a panel the vendor had
- * just accepted, and each was recorded as the model being wrong.
- */
+/** 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;
 export declare const SOLVE_DEFAULTS: {
     readonly maxSolveLoops: 6;
     readonly overallSolveTimeoutMs: 45000;
-    /**
-     * How long to hold a click waiting for the screen the model answered about.
-     *
-     * 9000, not the 6000 it was. A GeeTest svg board dwells p50 1.5s / p75 2.0s /
-     * max 2.7s per screen, so a 3-screen cycle runs 4.5s median and 8.1s worst
-     * case — a 6s budget could not catch the worst case however well aimed, and
-     * gave up one screen short. Named here rather than left as a literal in two
-     * places because `video_budget_ms` is derived from it on both ports and the
-     * arithmetic has to agree.
-     */
     readonly keyframeWaitTimeoutMs: 9000;
 };
-/**
- * How long a keyframe burst may run before it is called HUNG.
- *
- * A hang detector, not a budget: the solve timeout is what bounds real time.
- * This only has to notice a screenshot that never returns, so it is
- * deliberately slack.
- *
- * Sized off the CEILING, because that is what sizes the loop — the burst plans
- * `videoBurstMaxMs` worth of frames, not `videoBurstDurationMs` worth. Must
- * match `burst_hang_deadline_ms` in the python port, which had this guard
- * first and had it sized off the floor: a 120-frame burst got 17s, i.e. 141ms
- * per frame against a 100ms interval, and a burst that simply ran to its
- * ceiling killed the attempt.
- */
+/** A hang detector for a burst whose screenshot never returns, sized off the ceiling. */
 export declare function burstHangDeadlineMs(cfg: {
     videoBurstMaxMs?: number;
 }): number;
 export declare class CaptchaKrakenSolver {
     private config;
-    /** Extra ms this solve has been granted for a recording; see recordKeyframeBurst. */
     private videoBudgetMs;
     private videoBudgetGranted;
-    /**
-     * Every gesture goes through here, and it owns the pointer position. See
-     * humanize.ts — the solver names gestures, this decides what events they are
-     * and how long they take.
-     */
     private human;
-    private imageCounter;
-    private sessionDebugDir;
     private stepIndex;
     private solveStartMs;
-    private gridDebugDir;
-    private gridDebugSeq;
     private cvWorker;
     private cvWorkerReady;
     private cvWorkerSeq;
     private cvWorkerPending;
     private cvWorkerBuf;
+    /** Answers keyed by screenshot hash; a hit means the answer already ran and changed nothing. */
     private solutionCache;
     private repeatedAnswerSeen;
-    /**
-     * The ONE recording and the ONE answer for the animated challenge on screen.
-     *
-     * A cycling board needs a single inference and no more. The burst shows the
-     * model every screen; the answer names the cell AND the screen it is on
-     * (`frame` / `await_keyframe`); the gate then holds the click until that
-     * screen is back up. Nothing about that changes between rounds — the board
-     * keeps cycling through the same pictures with the same target — so asking
-     * again buys nothing and costs a burst plus a multi-image inference.
-     *
-     * It was asking again every round. Loops 3, 4 and 5 each re-recorded and
-     * re-inferred, which is what exhausted a 66s budget on a puzzle whose whole
-     * task is one click.
-     *
-     * Dropped when the gate reports it never saw the chosen screen: that means
-     * the widget is no longer the board this plan was made for, which is exactly
-     * when a fresh recording is warranted.
-     */
+    private retriedUnusableAnswer;
+    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;
-    /**
-     * How many distinct steady screens the current clip sits on; 0 if it is not
-     * that kind of clip. THE GATE KEYS ON THIS, NOT ON `keyframeMode`.
-     *
-     * `even` was being read as "no state recurs, do not wait". It does not mean
-     * that — it means the slicer could not PROVE recurrence, which for a board
-     * whose loop is longer than a 4s burst it never can. 32 of 60 real clips
-     * sliced `even` while sitting on 2-3 steady screens, so the gate was off on
-     * every real animated captcha and the driver clicked whichever screen was up.
-     */
     private keyframeSteadyScreens;
-    /**
-     * When the current solve must be over, in `Date.now()` terms. 0 outside one.
-     *
-     * The budget used to be checked ONLY at the top of each solve loop, so any
-     * single round could overrun it without limit — and an animated round is the
-     * long one: a 4s burst of 40 element screenshots, a multi-image inference,
-     * then a gated click per target. Measured on GeeTest svg, 2026-09-07: rounds
-     * that re-recorded ran past a 66s budget to the harness's own 180s ceiling
-     * and were reported "hung, not slow", which is a message about the model for
-     * a driver that simply never looked at the clock.
-     *
-     * The Python port has always checked mid-wait (`_check_deadline`), so this
-     * was also a cross-port divergence on exactly the puzzles Tier 3 times.
-     */
     private solveDeadlineAt;
     private lastAnswerSig;
     private noProgressRounds;
-    /** How far up planner.RESAMPLE_TEMPERATURES this BOARD has escalated. */
     private resampleLevel;
-    private state;
+    /** 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;
-    /** Interpreter + CLI root, resolved once. See resolveCli. */
     private cliCache;
-    /** The LoRA name models.json calls `latest`, read once. See askModel. */
     private loraNameCache;
-    /**
-     * Phase accounting for the CURRENT or MOST RECENT solve; see timing.ts.
-     * Null before the first solve, and readable after a failed one.
-     */
     budget: PhaseBudget | null;
-    /**
-     * Attribute the enclosed wall-clock to `name` for this solve's budget.
-     *
-     * A no-op outside a solve, so every helper stays callable from tests and from
-     * the watcher without a budget having been opened.
-     */
     private ph;
     constructor(config?: CaptchaKrakenConfig);
-    /**
-     * Where the pointer is. Owned by the humanizer, because a mode that
-     * dispatches no motion (mobile, between taps) still has to answer this.
-     */
     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`. */
+    private shot;
     solve(page: Page): Promise<SolveResult | void>;
-    /**
-     * Tell the hosted API whether the widget accepted — the one fact the server
-     * cannot see for itself, since a wrong answer reaches it as a 200 with
-     * well-formed JSON in it.
-     *
-     * THROUGH THE PYTHON CLI, not a `fetch` here. The endpoint, the credential,
-     * the extra-header handling and the "one 404 and stop asking" rule all live
-     * in `planner.report_outcome`; a second copy in TypeScript would agree with
-     * it until one of them was edited. That is the drift `model-name.ts` exists
-     * to prevent, on the same seam, and this port already crosses that subprocess
-     * boundary for every model call.
-     *
-     * NOT AWAITED, and detached. The solve is over and its result is decided, so
-     * nothing here may add latency to what the caller gets back or keep the
-     * process alive past it. `unref()` is what makes the second true.
-     */
+    /** Tell the hosted API whether the widget accepted, through the CLI, detached, never awaited. */
     private reportOutcome;
-    /**
-     * 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();
-     * ```
-     */
+    /** Solve captchas on `page` as they appear, until `stop()`. Injects nothing into the page. */
     watch(page: Page, options?: WatchOptions): CaptchaWatcher;
     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.
-     */
+    /** Fire the optional onStep observer with a fresh screenshot; best-effort, never fails the solve. */
     private emitStep;
     private solveSingle;
     private getVerifyButton;
-    private hasNonEmptyFieldValue;
-    /**
-     * WHICH of reCAPTCHA's three bframe banners is showing, if any.
-     *
-     * They share a corner and a look and they mean different things:
-     *
-     *   `rejected`      "Please try again."  The answer was wrong; a fresh board
-     *                   follows, so the useful response is to solve that one.
-     *   `select-more`   "Please select all matching images."  Under-selected, and
-     *                   the tiles do NOT refresh — so a driver that re-submits
-     *                   the same answer loops until the session times out. This
-     *                   is the one the missed-tiles retry and the abort exist for.
-     *   `dynamic-more`  "Please also check the new images."  NOT AN ERROR. It is
-     *                   the dynamic 3x3's normal flow: cleared tiles fade out,
-     *                   replacements fade in, and the widget says so — on
-     *                   essentially every round of that variant.
-     *
-     * This used to return a boolean over all three, which made the third one
-     * indistinguishable from the first two and armed the one-retry abort with the
-     * sentence that means "you are doing fine". Every dynamic board therefore
-     * died at round two while the vendor was still dealing. Measured 2026-09-06:
-     * three of three `recaptcha_3x3_fade` attempts stopped at exactly boards=2,
-     * against `recaptcha_4x4` passing at 2, 3 and 5 boards on the same run.
-     */
-    /**
-     * May a repeat of this banner end the solve?
-     *
-     * Only for the banners where repeating means STUCK. `dynamic-more` repeating
-     * means the board is still being cleared, which is progress, and treating it
-     * as fatal is the bug this pair of methods was split to fix.
-     */
+    /** Any element at `selector` carrying a non-blank value; response fields are hidden, so no visibility filter. */
+    private hasValue;
+    /** A visible match carrying text; an empty banner or prompt is a placeholder, not a signal. */
+    private visibleWithText;
+    private checkedIn;
     private bannerIsFatalAfterRetry;
-    private recaptchaBannerKind;
-    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.
-     */
+    /** Which verdict banner the open challenge shows; `dynamic-more` is the dynamic board's normal flow, not an error. */
+    private bannerKind;
+    /** The vendor's own done signal: a response token, a painted success state, or a checked box. */
     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.
-     */
+    /** A next round has painted, as opposed to the answered frame animating closed. */
     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.
-     */
-    /**
-     * Which vendors' code this page actually loaded.
-     *
-     * Read out of the page's own resource timing plus the `src`/`href` of
-     * everything it linked, so it works whenever it is called — a request
-     * listener would have to have been attached before navigation, and by the
-     * time a solve fails that ship has sailed.
-     *
-     * Best-effort by construction: the resource-timing buffer is finite and a
-     * page may have cleared it. An empty answer is "nothing seen", never "no
-     * captcha here". Mirrors `vendors_on_the_wire` in page_solver.py.
-     */
-    vendorsOnTheWire(page: Page): Promise<string[]>;
-    /**
-     * Why nothing was found — the two cases told apart. The old text guessed
-     * "reCAPTCHA v3 / invisible" every time, including the times a vendor had
-     * simply moved its DOM. See VENDOR_URL_MARKERS.
+     * Best-effort: hold until the board's pictures have painted. Nothing to wait for is ready, and so is no prompt: waiting
+     * on the prompt as a selector rejects when absent and paid the whole timeout per board.
      */
+    private waitForBoardImages;
+    /** Which vendors' code the page loaded, from resource timing and linked URLs. A tripwire, not a detector. */
+    vendorsOnTheWire(page: Page): Promise<Vendor[]>;
     private noWidgetMessage;
-    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.
-     */
-    /**
-     * The adapter name models.json calls `latest`, resolved once per solver.
-     *
-     * `resolveLoraName` reads models.json (and pinned_model.json) off disk
-     * SYNCHRONOUSLY, and it was doing that on every inference for a file that
-     * cannot change inside one process.
+     * Is a widget in the DOM at all, rendered or not? Invisible reCAPTCHA is excluded by its selector. The inline vendors
+     * count: without them this port failed fast in under a second on every GeeTest/Yidun page and disagreed with Python in Tier 3.
      */
+    hasInteractiveWidgetInDom(page: Page): Promise<boolean>;
+    /** Open challenges first, then unsolved checkboxes, then the inline vendors; every probe is queried at once. */
+    detectCaptcha(page: Page): Promise<Widget | null>;
+    /** A checkbox the vendor has already accepted is not a captcha to solve. */
+    private alreadyAccepted;
     private loraName;
+    /** The `--model` argv, or nothing: without VLLM_BASE_URL the CLI can see a credentials file this process cannot. */
+    private modelName;
     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.
-     */
+    /** 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;
-    /**
-     * 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.
-     */
+    /** Start the persistent CV worker once; false when it cannot start, so callers fall back to one-shot spawns. */
     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.
-     */
+    /** A CV tool through the worker when it is up, else a one-shot subprocess. Never throws. */
     private runCvTool;
+    /** A still board is not a loaded board: hold until the panel's centre carries structure. Returns how long it waited. */
+    private waitForBoardPainted;
     /**
-     * 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.
+     * Screenshot `el` every `intervalMs` until `judge(lastTwoFrames)` answers, or the time is up.
+     * A screenshot that fails ends the poll: the widget is gone or going.
      */
+    private pollFrames;
     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.
-     */
+    /** Per-cell state with the session's cached boxes: a blank mid-refresh frame has no lattice to detect. */
     private gridCellStates;
-    /** Order a loading set so `priority` cells (just-clicked) come first. */
     private orderByPriority;
+    private hoverLoop;
     /**
-     * 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.
+     * `chipped`: the photos were kept, press Verify. `loading`: those tiles are being swapped, read the board again.
+     * Chip is tested first: a chip zooms the photo, which reads as `changing` on the very frame that shows it.
      */
     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
-     * 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.
-     *
-     * 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.
-     */
+    /** Click, watch the clicked tiles, re-solve while they swap, submit on `done` or a chipped board. */
     private solveRecaptchaGrid;
     /**
-     * Record the animated challenge and return the directory holding the burst.
+     * 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.
      *
-     * 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.
+     * `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.
      *
-     * 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;
-    /**
-     * Start recording NOW, and let the caller decide later what it was for.
-     *
-     * This is what makes the speculative path possible. The burst is the only
-     * thing that can tell a cycling board from a still one, and it is also the
-     * recording that answers it — so it is started at the same moment the still
-     * screenshot goes to the model, and the two run together.
-     *
-     *   - the board never moves  -> `moved()` stays false, the still answer is
-     *     used, and the frames are thrown away. The recording cost nothing but
-     *     CPU, because it happened inside an inference we were already waiting
-     *     for.
-     *   - the board moves        -> the still answer is DISCARDED unread, the
-     *     burst runs on to the end of the cycle, and the multi-image answer is
-     *     the one acted on. Two inference CALLS, but only about one inference of
-     *     wall-clock, because the first ran during the recording.
-     *
-     * The old shape paid for that knowledge in whole ROUNDS: answer a still, act
-     * on it, notice nothing changed, answer another still, and only then record.
-     * ~15s of a 40s solve to learn something the first four frames already knew.
+     * 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 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.
-     */
+    /** Slice a burst into keyframes and solve them in one model request. The frame number is the guard. */
     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 the held-out sample corpus are `even` and `cycle` has never
-     * fired on real footage. Measured on an hCaptcha rotating-object animation: 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.
-     */
+    /** The session id 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;
+    /** Does the chosen keyframe's answer area appear in a sibling keyframe of the same clip? */
+    private answerRegionRecurs;
+    /** Hold until the widget looks like the keyframe around the action point, or the wait is spent. */
     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`.
-     */
+    /** Keyed on the retry mode too: the missed-tiles answer legitimately overlaps the previous one. */
     private static answerSignature;
-    /** Count consecutive identical answers; see `maxNoProgressRounds`. */
+    /** 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;
-    /**
-     * 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`.
-     */
+    /** A cache hit costs no inference, and means the answer already ran: the board cycles. */
     private answerFor;
     /**
-     * Should this round be recorded and solved from keyframes instead of read as
-     * a still?
+     * Drop the ANSWER, keep the camera.
      *
-     * 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.
+     * 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.
      */
-    /** Forget the recorded answer, and delete the frames it was holding. */
     private discardAnimatedPlan;
-    /**
-     * Should this round record while it asks?
-     *
-     * reCAPTCHA is excluded for the same reason it is excluded from the animated
-     * path at all: its dynamic 3x3 REPLACES tiles in place, has its own
-     * multi-round driver with its own fade gates, and its grids are never
-     * animated — so a burst there would film a fade and call it a cycle.
-     *
-     * Distorted-text rounds are excluded because the answer is a string, not a
-     * place, and nothing about a recording helps read one.
-     */
+    /** 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: build the CLI invocation, run it, parse what comes back. */
+    /** One inference through the CLI. */
     private askModel;
-    /**
-     * Query the model for `initialShot`, then guard against the captcha frame
-     * having changed DURING inference. reCAPTCHA/hCaptcha fade fresh tiles in over
-     * ~1s; if new imagery painted while the model was generating, its answer
-     * targets a stale ("undeveloped") frame and its tile picks / bboxes no longer
-     * line up with what's on screen. After the model returns we re-screenshot the
-     * element and diff it against the frame we sent (reusing the `check-movement`
-     * primitive); if it moved beyond the threshold we discard the answer and
-     * re-solve on the fresh frame, up to `maxStaleFrameReSolves` times, then act on
-     * the latest answer rather than spin.
-     *
-     * `runQuery` performs the actual model call for a given screenshot path (the
-     * caller wraps it in idle-wander where appropriate); it is re-invoked with the
-     * fresh path on each re-solve. Token usage from every query — including
-     * discarded ones — is accumulated, since those tokens were really spent. The
-     * caller owns `initialShot`; every fresh frame captured here is created and
-     * cleaned up here. Best-effort: a screenshot/diff failure falls through to the
-     * answer already in hand.
-     */
+    /** Re-solve when the frame changed during inference; twice means the board cycles. */
     private solveFrameFreshnessGuarded;
-    /**
-     * Screenshot the captcha element to a throwaway temp frame and diff it against
-     * `priorPath` (the frame we sent the model). Returns true when the frame
-     * changed beyond `threshold` — i.e. tiles faded in / refreshed since. Reuses
-     * the persistent CV worker's `check-movement` (falling back to a one-shot
-     * subprocess), the same frame-diff the settle detectors use. Cleans up its own
-     * temp frame. Best-effort: any screenshot/diff failure returns false so the
-     * caller acts on the answer it already has rather than spinning.
-     */
     private captchaFrameChangedSince;
-    /** Record a challenge-state transition. No-op for behaviour; logs the change
-     *  (via gridDebug, so only when CAPTCHA_DEBUG=1) for offline diagnosis. */
-    private setState;
-    /**
-     * Screenshot the challenge element to a throwaway file and return its sha1
-     * content hash (or null on failure). Used to tell whether the frame has
-     * changed (e.g. the post-submit transition to the next round). Cleans up.
-     */
     private elementFrameHash;
-    /**
-     * Monitor the challenge element until its pixels stop changing (settled), or
-     * until it's clear it never will (animated / video). Polls screenshots and
-     * diffs consecutive frames with `check-movement` (the persistent CV worker).
-     * Returns:
-     *   'settled'  — `settleFrames` consecutive frame-pairs showed no movement;
-     *                safe to screenshot for the model.
-     *   'animated' — it kept moving right up to `animatedChallengeAfterMs` without
-     *                ever settling → very likely a video/animated puzzle.
-     *   'timeout'  — neither happened within `settleTimeoutMs` (proceed best-effort).
-     *
-     * Note this is a *pixel* settle; the caller pairs it with the DOM-level
-     * `waitForHcaptchaChallengeImages` so a static loading frame (spinner on grey,
-     * below the pixel threshold) isn't mistaken for painted tiles. Cleans up.
-     */
+    /** Poll until the pixels stop changing. `motionStreak` exits early: rotating_obj_video changes every 133-171ms and once spent 4.5s proving it. */
     private waitForElementSettled;
-    /**
-     * After a submit we EXPECT the challenge frame to change (advance to the next
-     * round, or close because it was accepted). Poll until the element's content
-     * hash differs from `sinceHash` — the transition beginning — so we never
-     * screenshot/solve the pre-transition frame again. Returns true once it
-     * changed, false if it never changed within `postSubmitChangeTimeoutMs` (e.g.
-     * it was already the final state). Best-effort.
-     */
     private waitForChangeSince;
-    /**
-     * 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 humanizer as real clicks, so a
-     * mode with no cursor skips it entirely; cancelled the instant `fn` resolves.
-     * Best-effort — any wander error is swallowed and never fails the solve.
-     * Disable via config.idleMouseWander.
-     */
+    /** Drift the cursor over the widget while `fn` (the model call) runs; cancelled the instant it resolves. */
     private withIdleWander;
     move(page: Page, selectorOrElement: string | ElementHandle, options?: {
         paddingPercentage?: number;
     }): Promise<void>;
     moveAndClick(page: Page, element: ElementHandle): Promise<void>;
-    /**
-     * Travel to a point. What that MEANS is the humanizer's business — on a
-     * touchscreen with no finger down it is a bookkeeping update and emits
-     * nothing at all.
-     */
     private performSmoothMove;
-    /**
-     * Where in the element this click lands, in element-relative pixels.
-     *
-     * Split out of `executeClick` because on an animated board the point has to
-     * be chosen ONCE and then used three times — to park the pointer, to ask
-     * `match-region` about the right neighbourhood, and to press. Choosing it
-     * inside the click (it is randomised within the target) meant the gate
-     * watched the bbox centre while the press landed somewhere else.
-     */
+    /** Element-relative click point: a random spot inside the box, inset 10% off its border. */
     private clickPointFor;
-    /**
-     * Click one target on an ANIMATED board, at the moment its screen is up.
-     *
-     * The order is the point of it. The pointer is parked on the target FIRST,
-     * then the gate opens, then the press happens in place — so the only thing
-     * between "the right screen is showing" and the click is a mouse-down.
-     *
-     * It used to wait and then call `executeClick`, which begins with a humanised
-     * move: 274ms p10 / 398ms p50 / 647ms max across a 340x384 widget, against a
-     * 1500ms median dwell. A quarter to a third of the screen's life spent
-     * travelling after we had already confirmed it was the right one — so the
-     * gate could do its job and the click still land on the next screen.
-     * `move()` short-circuits when it is already at the target, so parking early
-     * costs nothing and removes all of it.
-     */
+    /** Park on the target first, so only a mouse-down separates the right screen from the click. */
     private clickWhenFrameMatches;
     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.
+     * The slider piece's box: the first visible match small enough to be a piece. Runs during detection, so it must
+     * not set `actedOnBoard`: marking there disabled `shouldSpeculate` on every slide solve.
      */
+    private measurePieceBox;
     private findControl;
     /**
-     * Where a distorted-text captcha's answer goes.
-     *
-     * Inside the widget first. If the widget holds no text box at all, widen ONCE
-     * to its enclosing <fieldset>/<form> and look again for a VENDOR-NAMED box
-     * only.
-     *
-     * BotDetect is why, and nothing else needs it. BotDetect is a self-hosted
-     * LIBRARY, so the host application owns the layout: measured on captcha.com
-     * 2026-08-24, `.BDC_CaptchaDiv` — the element detectCaptcha returns — is
-     * 280x50 and holds the image alone, while `#captchaCode` sits in a sibling
-     * `<div class="validationDiv">` under the enclosing <fieldset>. Scoped to the
-     * widget the solver found no box, textMode stayed false, and it read the code
-     * correctly and never typed it. A clean solve thrown away, and
-     * indistinguishable in any report from a model that cannot read warped text.
-     *
-     * The widened pass is restricted to TEXT_INPUT_VENDOR_SELECTORS on purpose.
-     * The generic tail is what makes the in-widget lookup work for every other
-     * vendor, and OUTSIDE the widget it is exactly how a captcha's answer ends up
-     * in a login form's username box. One level, named selectors, never the page.
-     *
-     * Mirrors `_answer_box` in page_solver.py — CLAUDE.md 1c.
+     * The text box inside the widget, else a vendor-named one in its enclosing fieldset/form, never the page: the generic
+     * tail outside the widget is how a captcha's answer lands in a login form's username box. The widening exists for
+     * BotDetect, whose 280x50 `.BDC_CaptchaDiv` holds only the image while `#captchaCode` sits in a sibling div.
      */
     private answerBox;
-    /** 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.
-     */
-    /**
-     * Device pixels per CSS pixel, read off the shot we are about to measure.
-     * 1 when the image cannot be read — an unreadable shot is already the
-     * trackPiece-returns-null path, and guessing a ratio would steer by it.
-     */
     private shotScale;
+    /** Aim the handle at the slot once, then look and correct until the piece is home. Release is the submit. */
     private executeSlide;
 }