captchakraken 2.4.0 → 2.6.0

package/dist/trajectory.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Human-like mouse trajectories for the page driver.
+ *
+ * The TypeScript side of `python/src/captchakraken/trajectory.py`; the two are
+ * one implementation in two languages, pinned by `test_trajectory_parity.py`.
+ *
+ * What makes the output human rather than a lerp:
+ *   - a Bezier arc, not a straight line (hand motion bows)
+ *   - Fitts's-law duration: distance and precision set the time, not a constant
+ *   - an ease-in-out velocity profile, so the cursor accelerates then brakes
+ *   - sub-pixel jitter that scales with speed (fast motion is sloppier)
+ *   - a small overshoot-and-correct on longer moves, which is the single most
+ *     recognisable human tell and the one a linear interpolation never produces
+ *
+ * Camoufox's own `humanize` is a DIFFERENT, browser-level mechanism that
+ * re-humanises every `mouse.move()` it is handed. Running both composes them —
+ * measured 82.1s vs 13.4s on one geetest_v4_slide solve, because each of the 60
+ * points below became its own humanised sub-trajectory. Drive with humanize off.
+ */
+export type Point = [number, number];
+/**
+ * Returns `[points, timings]`. `timings` is CUMULATIVE milliseconds from the
+ * gesture start — not per-step deltas — because that is what `tracePath` sleeps
+ * against, and both drivers must pace identically.
+ *
+ * `frequency` is samples per second (the driver passes 60).
+ * `frequencyRandomizer` jitters each frame's timestamp so the sample interval
+ * is not a metronome; a perfectly periodic mousemove stream is trivially
+ * detectable.
+ */
+export declare function generate_trajectory(target_start: readonly number[], target_end: readonly number[], frequency?: number, frequencyRandomizer?: number): [Point[], number[]];

package/dist/trajectory.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Human-like mouse trajectories for the page driver.
+ *
+ * The TypeScript side of `python/src/captchakraken/trajectory.py`; the two are
+ * one implementation in two languages, pinned by `test_trajectory_parity.py`.
+ *
+ * What makes the output human rather than a lerp:
+ *   - a Bezier arc, not a straight line (hand motion bows)
+ *   - Fitts's-law duration: distance and precision set the time, not a constant
+ *   - an ease-in-out velocity profile, so the cursor accelerates then brakes
+ *   - sub-pixel jitter that scales with speed (fast motion is sloppier)
+ *   - a small overshoot-and-correct on longer moves, which is the single most
+ *     recognisable human tell and the one a linear interpolation never produces
+ *
+ * Camoufox's own `humanize` is a DIFFERENT, browser-level mechanism that
+ * re-humanises every `mouse.move()` it is handed. Running both composes them —
+ * measured 82.1s vs 13.4s on one geetest_v4_slide solve, because each of the 60
+ * points below became its own humanised sub-trajectory. Drive with humanize off.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate_trajectory = generate_trajectory;
+// Fitts's law: MT = a + b * log2(distance / width + 1). The constants are the
+// usual empirical range for a mouse; `WIDTH` stands in for target precision.
+const FITTS_A_MS = 90.0;
+const FITTS_B_MS = 105.0;
+const WIDTH_PX = 28.0;
+// Below this, a move is a nudge inside one element: no overshoot, no arc.
+const SHORT_MOVE_PX = 24.0;
+// Overshooting a 30px hop looks like a twitch, not a human.
+const OVERSHOOT_MIN_DISTANCE_PX = 220.0;
+/** Cubic ease. Real pointer motion is roughly bell-shaped in velocity. */
+function easeInOut(t) {
+    if (t < 0.5)
+        return 4.0 * t * t * t;
+    return 1.0 - Math.pow(-2.0 * t + 2.0, 3) / 2.0;
+}
+function cubicBezier(p0, p1, p2, p3, t) {
+    const u = 1.0 - t;
+    const x = u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0];
+    const y = u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1];
+    return [x, y];
+}
+function uniform(lo, hi) {
+    return lo + Math.random() * (hi - lo);
+}
+/**
+ * Box-Muller. `Math.random()` is uniform and the jitter model wants a normal
+ * deviate; a uniform one has hard edges that show up as a boxy distribution of
+ * off-path error, which is itself a fingerprint.
+ */
+function gauss(mu, sigma) {
+    let u = 0;
+    while (u === 0)
+        u = Math.random(); // log(0) is -Infinity
+    const v = Math.random();
+    return mu + sigma * Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+}
+/**
+ * Two control points offset PERPENDICULAR to the travel direction, so the path
+ * bows to one side. The sign is random per gesture: always bowing the same way
+ * would itself be a fingerprint.
+ */
+function controlPoints(start, end, distance) {
+    const dx = end[0] - start[0];
+    const dy = end[1] - start[1];
+    if (distance === 0)
+        return [start, end];
+    // Unit normal to the direction of travel.
+    const nx = -dy / distance;
+    const ny = dx / distance;
+    // Bow proportional to distance, but capped — long drags don't arc absurdly.
+    const bow = Math.min(distance * uniform(0.06, 0.16), 140.0) * (Math.random() < 0.5 ? -1.0 : 1.0);
+    // Control points at roughly 1/3 and 2/3 along, each pushed off-axis.
+    const c1 = [
+        start[0] + dx * uniform(0.2, 0.4) + nx * bow,
+        start[1] + dy * uniform(0.2, 0.4) + ny * bow,
+    ];
+    const c2 = [
+        start[0] + dx * uniform(0.6, 0.8) + nx * bow * uniform(0.4, 0.9),
+        start[1] + dy * uniform(0.6, 0.8) + ny * bow * uniform(0.4, 0.9),
+    ];
+    return [c1, c2];
+}
+/**
+ * Returns `[points, timings]`. `timings` is CUMULATIVE milliseconds from the
+ * gesture start — not per-step deltas — because that is what `tracePath` sleeps
+ * against, and both drivers must pace identically.
+ *
+ * `frequency` is samples per second (the driver passes 60).
+ * `frequencyRandomizer` jitters each frame's timestamp so the sample interval
+ * is not a metronome; a perfectly periodic mousemove stream is trivially
+ * detectable.
+ */
+function generate_trajectory(target_start, target_end, frequency = 60, frequencyRandomizer = 0.12) {
+    const start = [Number(target_start[0]), Number(target_start[1])];
+    const end = [Number(target_end[0]), Number(target_end[1])];
+    const dx = end[0] - start[0];
+    const dy = end[1] - start[1];
+    const distance = Math.hypot(dx, dy);
+    if (distance < 1e-6)
+        return [[end], [0.0]];
+    let durationMs = FITTS_A_MS + FITTS_B_MS * Math.log2(distance / WIDTH_PX + 1.0);
+    durationMs *= uniform(0.85, 1.2);
+    const steps = Math.max(2, Math.round((durationMs / 1000.0) * Math.max(1, frequency)));
+    // A short hop is a straight ease with jitter — bowing a 15px move looks worse
+    // than not bowing it.
+    let c1;
+    let c2;
+    if (distance < SHORT_MOVE_PX) {
+        c1 = start;
+        c2 = end;
+    }
+    else {
+        [c1, c2] = controlPoints(start, end, distance);
+    }
+    // Overshoot: on a long move the hand arrives past the target and corrects.
+    // Modelled as a longer primary gesture to a point beyond the target, then a
+    // short settle back — the settle is appended as extra samples below.
+    const overshoot = distance >= OVERSHOOT_MIN_DISTANCE_PX && Math.random() < 0.55;
+    let aim = end;
+    if (overshoot) {
+        const over = uniform(0.01, 0.035) * distance;
+        aim = [end[0] + (dx / distance) * over, end[1] + (dy / distance) * over];
+    }
+    const points = [];
+    const timings = [];
+    let elapsed = 0.0;
+    const perStep = durationMs / steps;
+    for (let i = 0; i <= steps; i++) {
+        const t = easeInOut(i / steps);
+        let [px, py] = cubicBezier(start, c1, c2, aim, t);
+        // Jitter scales with instantaneous speed: the faster the cursor is moving,
+        // the less precisely a human tracks the intended path.
+        const speed = Math.abs(easeInOut(Math.min(1.0, (i + 1) / steps)) - easeInOut(i / steps));
+        const jitter = Math.min(1.6, 0.25 + speed * steps * 0.5);
+        px += gauss(0.0, jitter * 0.5);
+        py += gauss(0.0, jitter * 0.5);
+        points.push([px, py]);
+        timings.push(elapsed);
+        elapsed += perStep * uniform(1.0 - frequencyRandomizer, 1.0 + frequencyRandomizer);
+    }
+    if (overshoot) {
+        // Correction: a couple of small samples back onto the true target, at the
+        // slower pace of a deliberate fine adjustment.
+        const settleSteps = Math.floor(uniform(2, 5)); // 2..4 inclusive
+        const origin = points[points.length - 1];
+        for (let i = 1; i <= settleSteps; i++) {
+            const t = i / settleSteps;
+            points.push([
+                origin[0] + (end[0] - origin[0]) * t + gauss(0.0, 0.35),
+                origin[1] + (end[1] - origin[1]) * t + gauss(0.0, 0.35),
+            ]);
+            timings.push(elapsed);
+            elapsed += uniform(14.0, 30.0);
+        }
+    }
+    // Land exactly on the requested pixel. Everything above is texture; the final
+    // sample must be the point the caller asked for or clicks drift off-target.
+    points[points.length - 1] = end;
+    return [points, timings];
+}

package/dist/types.d.ts

@@ -12,12 +12,13 @@ export interface SolveStepEvent {
      * Coarse stage kind:
      *  - `initial`  : screenshot taken before any action (baseline)
      *  - `click`    : after a click (or batch of clicks) was executed
-     *  - `drag`     : after a drag was executed
+     *  - `drag`     : after a drag was executed (a slider counts as one)
+     *  - `type`     : after a distorted-text answer was typed into its box
      *  - `wait`     : after a CLI-requested wait elapsed
      *  - `submit`   : after the Verify/Next/Submit button was clicked
      *  - `round`    : a dynamic reCAPTCHA 3x3 round boundary (pre-solve snapshot)
      */
-    stage: 'initial' | 'click' | 'drag' | 'wait' | 'submit' | 'round';
+    stage: 'initial' | 'click' | 'drag' | 'type' | 'wait' | 'submit' | 'round';
     /** Short human label, e.g. "round-2:clicked 3 tile(s)". */
     label: string;
     /**
@@ -68,8 +69,13 @@ export interface CaptchaKrakenConfig {
      */
     pythonCommand?: string;
     /**
-     * vLLM LoRA name to invoke (default: 'captcha' — our bbox-aware LoRA).
-     * Override if you've registered a different module with the vLLM server.
+     * vLLM LoRA name to invoke.
+     *
+     * Defaults to whatever `models.json` calls `latest` (via CAPTCHA_LORA_NAME if
+     * set) — NOT a literal. The name selects the PROMPT GENERATION as well as the
+     * weights, so a constant here would pin the prompts to one generation while
+     * `latest` moved on. Override only if you've registered a different module
+     * with the vLLM server; see model-name.ts.
      */
     model?: string;
     /**
@@ -88,9 +94,30 @@ export interface CaptchaKrakenConfig {
      * Automatically re-check for newly opened / next-step captchas after each solve
      * attempt (e.g., clicking a checkbox opens an image challenge).
      *
-     * Default: 10
+     * The loop count that FITS inside overallSolveTimeoutMs, rather than one that
+     * needs policing by the clock: a round costs ~4-7s, so six rounds is the 45s
+     * budget. A backstop, not the normal way a hopeless solve ends — that is
+     * maxNoProgressRounds. Reaching this number is a bug report.
+     *
+     * Default: 6
      */
     maxSolveLoops?: number;
+    /**
+     * Consecutive rounds producing the SAME answer before the solve is abandoned.
+     *
+     * At temperature 0 the model is a function of the picture, so an identical
+     * answer means an identical picture — and every answer this driver produces is
+     * EXECUTED, so the previous one already ran and moved nothing. Repeating it
+     * cannot do better; it just spends a round.
+     *
+     * 2 rather than 1 because the first repeat also escalates to a RECORDING (see
+     * shouldRetryAsAnimated), which is the one recovery worth trying: a cycling
+     * board reads as a still and answers the same way every round. One more round
+     * buys that chance.
+     *
+     * Default: 2
+     */
+    maxNoProgressRounds?: number;
     /**
      * Delay (ms) after executing actions before re-detecting captchas.
      * Useful to allow challenge frames / new images to appear.
@@ -101,7 +128,7 @@ export interface CaptchaKrakenConfig {
     /**
      * Overall time limit (ms) for the entire solve loop.
      *
-     * Default: 120000 (2 minutes)
+     * Default: 45000
      */
     overallSolveTimeoutMs?: number;
     /**
@@ -184,9 +211,26 @@ export interface CaptchaKrakenConfig {
      * soon as the solved signal appears avoids re-entering the solve pipeline on a
      * challenge frame that is merely animating closed.
      *
-     * Default: 4000
+     * That is the window's whole job, and it is why a WRONG answer spends all of
+     * it: the vendors emit nothing on a wrong answer, they just re-deal. So
+     * sizing it means asking how late a real SUCCESS can arrive — measured over
+     * 34 successful rounds across 20 puzzle types on the fixture server: p50
+     * 360ms, max 528ms. 1000ms is that worst case plus headroom for a vendor
+     * round-trip nobody has measured yet. Down from 2500, which was spent in full
+     * on every unsuccessful round.
+     *
+     * Default: 1000
      */
     postSolveOutcomeTimeoutMs?: number;
+    /**
+     * Poll interval (ms) inside that window.
+     *
+     * The success signals are polled, so detection latency is a MULTIPLE of this.
+     * Each poll is a couple of cheap DOM reads.
+     *
+     * Default: 75
+     */
+    postSolveOutcomePollMs?: number;
     /**
      * Guard against the captcha frame changing WHILE the model is generating.
      * reCAPTCHA/hCaptcha fade fresh tiles in over ~1s; if new imagery paints
@@ -225,6 +269,12 @@ export interface CaptchaKrakenConfig {
      * Default: 0.01
      */
     settleDiffThreshold?: number;
+    /**
+     * How long to wait for hCaptcha's task images to paint before screenshotting
+     * anyway. Best-effort by design — the screenshot happens either way — so it
+     * is bounded by what a loading tile plausibly costs. Default: 3000
+     */
+    hcaptchaImagesTimeoutMs?: number;
     /** Poll interval (ms) for the settle monitor. Default: 220 */
     settlePollMs?: number;
     /**
@@ -245,6 +295,41 @@ export interface CaptchaKrakenConfig {
      * Default: 4500
      */
     animatedChallengeAfterMs?: number;
+    /**
+     * Record and solve animated challenges. When false, a challenge that never
+     * settles fails with `.animated = true` as it did before — for callers who
+     * would rather fail fast than spend the recording time.
+     *
+     * Default: true
+     */
+    videoSolveEnabled?: boolean;
+    /**
+     * Length (ms) and frame rate of the burst recorded from an animated challenge.
+     *
+     * Do not tune these casually. They are deliberately identical to the geometry
+     * the training corpus was collected at (4000ms @ 10fps), and the keyframe
+     * slicer reads the clip's temporal structure — a different length or rate
+     * changes where a cycle's period lands across the frames, so the live set gets
+     * sliced differently from the trained set and the model's frame number stops
+     * meaning what the driver thinks it means.
+     *
+     * Defaults: 4000 / 10
+     */
+    videoBurstDurationMs?: number;
+    videoBurstFps?: number;
+    /**
+     * How long (ms) to wait for the widget to return to the keyframe the model
+     * chose, before clicking anyway; and the poll interval while waiting.
+     *
+     * Bounded because the alternative is worse: these puzzles cycle, so the state
+     * does come back — but if the recording caught a one-off transition it never
+     * will, and a click on the model's coordinates is a better use of the
+     * remaining budget than a timeout.
+     *
+     * Defaults: 6000 / 120
+     */
+    keyframeWaitTimeoutMs?: number;
+    keyframeWaitPollMs?: number;
     /**
      * After clicking Submit/Verify, the solver EXPECTS the frame to change (advance
      * to the next round, or close because it was accepted). This is how long (ms)
@@ -297,7 +382,27 @@ export interface BoundingBox {
     2: number;
     3: number;
 }
-export interface ClickAction {
+/**
+ * Fields present ONLY on actions from an animated challenge.
+ *
+ * Why an action carries a picture: on an animated puzzle the target is visible
+ * only part of the time, so the coordinates are correct only while the widget
+ * looks the way it did in that keyframe. The driver holds the mouse until the
+ * live neighbourhood around the click point matches the same neighbourhood of
+ * `await_keyframe`, then clicks. Without the wait, a click on a fading sprite
+ * lands on background.
+ *
+ * Both are set together or not at all — a number with no image cannot be waited
+ * on, and an image with no number cannot be reported. Absent on every still
+ * puzzle, where there is no moment to wait for.
+ */
+export interface AnimatedActionFields {
+    /** Absolute path to the keyframe the model chose to act on. */
+    await_keyframe?: string | null;
+    /** Its 1-based number in the keyframe set that was sent. */
+    frame?: number | null;
+}
+export interface ClickAction extends AnimatedActionFields {
     action: 'click';
     /**
      * One or more normalized [x1, y1, x2, y2] bboxes (0–1 fractions of the
@@ -310,11 +415,23 @@ export interface ClickAction {
     target_bounding_box?: [number, number, number, number] | null;
     target_coordinates?: [number, number] | null;
 }
-export interface DragAction {
+export interface DragAction extends AnimatedActionFields {
     action: 'drag';
-    source_bounding_box: [number, number, number, number];
+    /**
+     * Null on a PUZZLE-PIECE SLIDER. Not a missing field — the shape of the
+     * answer: what you grab (a handle, elsewhere on the widget) is not what has
+     * to arrive (the piece), and how far one moves the other is a vendor detail
+     * no picture reveals. The driver reads a null source as "find the slider and
+     * close the loop on the piece" (see executeSlide).
+     */
+    source_bounding_box: [number, number, number, number] | null;
     target_bounding_box: [number, number, number, number];
 }
+/** Distorted-text captchas: the answer is a string, not a place. */
+export interface TypeAction {
+    action: 'type';
+    text: string;
+}
 export interface DoneAction {
     action: 'done';
 }
@@ -322,7 +439,7 @@ export interface WaitAction {
     action: 'wait';
     duration_ms: number;
 }
-export type CaptchaAction = ClickAction | WaitAction | DragAction | DoneAction;
+export type CaptchaAction = ClickAction | WaitAction | DragAction | TypeAction | DoneAction;
 export type SolverResult = CaptchaAction | CaptchaAction[];
 export interface TokenUsage {
     input_tokens: number;

package/dist/watcher.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Auto-solve watcher — install once, and captchas are solved as they appear.
+ *
+ * WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
+ * The obvious implementation is a `MutationObserver` inside the page that calls
+ * out through `exposeBinding`. That is faster to react, and it is also the one
+ * design that cannot be made stealthy on every platform: `exposeBinding` puts a
+ * function on `window` and an observer is script the page can enumerate. On
+ * Camoufox both are sandboxed and invisible; on vanilla Playwright or Puppeteer
+ * they are not, and a captcha vendor is exactly the party that looks.
+ *
+ * So the watcher injects NOTHING. It drives the same `detectCaptcha()` the
+ * solver already uses, from the driver side, on a timer. Consequences worth
+ * knowing:
+ *
+ *   - Nothing is added to the page on ANY platform, so there is no new
+ *     detection surface to reason about per launcher.
+ *   - On Camoufox the probe's DOM reads run in Camoufox's isolated Juggler
+ *     world for free — that is its default for all Playwright evaluation
+ *     (`main_world_eval` / an `mw:` prefix is the opt-OUT). The watcher never
+ *     opts out, so it is isolated there by construction, not by special-casing.
+ *   - Reaction time is bounded by `intervalMs`, not by the mutation itself.
+ *     A captcha that appears just after a tick waits up to one interval.
+ *
+ *
+ * ONE WATCHER COVERS THE WHOLE PAGE, FOR ITS WHOLE LIFE
+ * A `Page` outlives navigation, and so does the watcher holding it: install it
+ * once and it keeps probing across every `goto`, staying quiet while there is
+ * nothing to solve and re-arming after each solve. That is deliberately the
+ * whole API — the case that motivates a browser-wide installer is almost always
+ * a challenge appearing on request 40 of a run, on the SAME page object the run
+ * started with, and that is already covered by one line. Pinned in
+ * browser-compat.test.ts.
+ * DETECTION IS THE SOLVER'S, NOT A COPY
+ * The trigger is `solver.detectCaptcha(page)`, the same method `solve()` calls,
+ * so "what counts as a captcha" has exactly one definition. An earlier sketch
+ * kept a union of the vendor selectors here for a cheaper single-roundtrip
+ * probe; it drifted from VENDOR_WIDGET_LOCATORS the first time a vendor was
+ * added, which is the failure this indirection exists to prevent.
+ *
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver();
+ * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
+ * // ... your automation runs; captchas are solved underneath it ...
+ * await watcher.stop();
+ * ```
+ */
+import { PlaywrightPage as Page } from './playwright-types';
+import { SolveResult } from './types';
+/**
+ * The slice of the solver the watcher drives.
+ *
+ * Structural rather than an import of `CaptchaKrakenSolver` so this module has
+ * no runtime dependency on solver.ts (which imports this one for the `watch()`
+ * method — a real cycle under CommonJS), and so tests can drive it with a fake.
+ */
+export interface WatchableSolver {
+    detectCaptcha(page: Page): Promise<unknown | null>;
+    solve(page: Page): Promise<SolveResult | void>;
+}
+export interface WatchOptions {
+    /**
+     * Milliseconds between detection probes. Default 1000.
+     *
+     * This is the latency floor for noticing a captcha, and each tick costs one
+     * `detectCaptcha()` — a handful of selector queries. Below ~250ms you are
+     * paying real CPU for latency the solve itself (seconds) makes irrelevant.
+     */
+    intervalMs?: number;
+    /** Stop automatically after this many successful solves. Default: unlimited. */
+    maxSolves?: number;
+    /**
+     * Wait this long after a solve THROWS before probing again. Default 5000.
+     *
+     * Without it a permanently unsupported challenge — an invisible reCAPTCHA v3,
+     * say — turns the watcher into a hot loop that re-attempts and re-bills every
+     * `intervalMs` forever.
+     */
+    errorBackoffMs?: number;
+    /** Called after each solve that returns a result. Exceptions here are swallowed. */
+    onSolved?: (result: SolveResult) => void | Promise<void>;
+    /**
+     * Called when detection or solving throws. Exceptions here are swallowed.
+     *
+     * Errors are reported, never fatal: `NoCaptchaFoundError` fires routinely
+     * when a widget disappears between the probe and the solve, and a watcher
+     * that died on it would be useless.
+     */
+    onError?: (error: unknown) => void | Promise<void>;
+}
+export interface CaptchaWatcher {
+    /** Stop probing and resolve once any in-flight solve has finished. */
+    stop(): Promise<void>;
+    /** False once stopped, the page closed, or `maxSolves` was reached. */
+    readonly running: boolean;
+    /** Successful solves so far. */
+    readonly solves: number;
+}
+export declare function watchPage(solver: WatchableSolver, page: Page, options?: WatchOptions): CaptchaWatcher;

package/dist/watcher.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Auto-solve watcher — install once, and captchas are solved as they appear.
+ *
+ * WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
+ * The obvious implementation is a `MutationObserver` inside the page that calls
+ * out through `exposeBinding`. That is faster to react, and it is also the one
+ * design that cannot be made stealthy on every platform: `exposeBinding` puts a
+ * function on `window` and an observer is script the page can enumerate. On
+ * Camoufox both are sandboxed and invisible; on vanilla Playwright or Puppeteer
+ * they are not, and a captcha vendor is exactly the party that looks.
+ *
+ * So the watcher injects NOTHING. It drives the same `detectCaptcha()` the
+ * solver already uses, from the driver side, on a timer. Consequences worth
+ * knowing:
+ *
+ *   - Nothing is added to the page on ANY platform, so there is no new
+ *     detection surface to reason about per launcher.
+ *   - On Camoufox the probe's DOM reads run in Camoufox's isolated Juggler
+ *     world for free — that is its default for all Playwright evaluation
+ *     (`main_world_eval` / an `mw:` prefix is the opt-OUT). The watcher never
+ *     opts out, so it is isolated there by construction, not by special-casing.
+ *   - Reaction time is bounded by `intervalMs`, not by the mutation itself.
+ *     A captcha that appears just after a tick waits up to one interval.
+ *
+ *
+ * ONE WATCHER COVERS THE WHOLE PAGE, FOR ITS WHOLE LIFE
+ * A `Page` outlives navigation, and so does the watcher holding it: install it
+ * once and it keeps probing across every `goto`, staying quiet while there is
+ * nothing to solve and re-arming after each solve. That is deliberately the
+ * whole API — the case that motivates a browser-wide installer is almost always
+ * a challenge appearing on request 40 of a run, on the SAME page object the run
+ * started with, and that is already covered by one line. Pinned in
+ * browser-compat.test.ts.
+ * DETECTION IS THE SOLVER'S, NOT A COPY
+ * The trigger is `solver.detectCaptcha(page)`, the same method `solve()` calls,
+ * so "what counts as a captcha" has exactly one definition. An earlier sketch
+ * kept a union of the vendor selectors here for a cheaper single-roundtrip
+ * probe; it drifted from VENDOR_WIDGET_LOCATORS the first time a vendor was
+ * added, which is the failure this indirection exists to prevent.
+ *
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver();
+ * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
+ * // ... your automation runs; captchas are solved underneath it ...
+ * await watcher.stop();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchPage = watchPage;
+/** A page that has closed, where the launcher exposes that (Playwright and Puppeteer both do). */
+function isPageClosed(page) {
+    return typeof page.isClosed === 'function' ? page.isClosed() : false;
+}
+/** Report to a user callback without letting its failure reach the loop. */
+async function report(fn, value) {
+    if (!fn)
+        return;
+    try {
+        await fn(value);
+    }
+    catch {
+        // A throwing callback is the caller's bug and must not stop the watcher.
+    }
+}
+function watchPage(solver, page, options = {}) {
+    const intervalMs = options.intervalMs ?? 1000;
+    const errorBackoffMs = options.errorBackoffMs ?? 5000;
+    const maxSolves = options.maxSolves ?? Infinity;
+    let running = true;
+    let solves = 0;
+    // Resolved by the loop on its way out, so stop() can await a solve in flight.
+    // Definite assignment: the Promise executor runs synchronously, so `finished`
+    // is set before any code below can reach it — TS cannot prove that itself.
+    let finished;
+    const done = new Promise((resolve) => { finished = resolve; });
+    // Held so stop() can cut a pending sleep short instead of waiting it out.
+    let wake = null;
+    const sleep = (ms) => new Promise((resolve) => {
+        const timer = setTimeout(() => { wake = null; resolve(); }, ms);
+        wake = () => { clearTimeout(timer); wake = null; resolve(); };
+    });
+    (async () => {
+        try {
+            while (running) {
+                await sleep(intervalMs);
+                if (!running)
+                    break;
+                if (isPageClosed(page))
+                    break;
+                try {
+                    if (!(await solver.detectCaptcha(page)))
+                        continue;
+                    // Re-check: detectCaptcha can take a moment, and stop() during it
+                    // should not be followed by a fresh multi-second solve.
+                    if (!running)
+                        break;
+                    const result = await solver.solve(page);
+                    if (result) {
+                        solves += 1;
+                        await report(options.onSolved, result);
+                    }
+                    if (solves >= maxSolves)
+                        break;
+                }
+                catch (error) {
+                    if (isPageClosed(page))
+                        break;
+                    await report(options.onError, error);
+                    await sleep(errorBackoffMs);
+                }
+            }
+        }
+        finally {
+            running = false;
+            finished();
+        }
+    })();
+    return {
+        stop() {
+            running = false;
+            if (wake)
+                wake();
+            return done;
+        },
+        get running() { return running; },
+        get solves() { return solves; },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captchakraken",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Browser-agnostic Playwright/Puppeteer captcha solver. Detects the captcha, reads the grid with a fine-tuned Qwen3.5-9B vision model on vLLM, and clicks through to a token.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
     "prebuild": "node scripts/copy-python.mjs",
     "build": "tsc",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "tsc --noEmit -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test .test-build/*.test.js",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/setup-python.js"
   },
@@ -43,8 +43,5 @@
   "devDependencies": {
     "@types/node": "^24.10.2",
     "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "cursory-ts": "^1.0.0"
   }
 }