captchakraken 2.9.0 → 3.0.0

package/dist/humanize.d.ts

@@ -1,92 +1,28 @@
 /**
- * How the driver MOVES. One pluggable object per input device.
+ * How the driver moves: one pluggable object per input device. Mirrors python/humanize.py.
  *
- * The TypeScript side of `python/src/captchakraken/humanize.py`; the two are one
- * design in two languages, and `the training repo's humanizer parity tests` in
- * the training repo pins that the mode names and the pause vocabulary have
- * not drifted.
+ * The pointer position lives here, not in the solver, because a touch mode that dispatches no
+ * motion between taps still has to say where the next gesture starts.
  *
- * Humanisation used to be wired straight into `solver.ts`: every gesture was a
- * `page.mouse.*` call with a Bezier trajectory in front of it and a `Math.
- * random()` sleep behind it, and there was no way to ask for anything else. That
- * is wrong in three directions at once —
- *
- *   - a caller driving a MOBILE page has no cursor. Dispatching mousemove at a
- *     touch-only widget is not weak humanisation, it is the wrong event type:
- *     the page's touch handlers never fire, and a vendor that scores pointer
- *     telemetry sees a desktop mouse on a phone.
- *   - a caller who has their OWN humanisation (a hardware pointer, a proxied
- *     device farm, a model of their own users) was composing two of them. That
- *     is not hypothetical — camoufox's `humanize` juggler re-humanises every
- *     `mouse.move()` it is handed, and running both measured 82.1s against
- *     13.4s on one a GeeTest v4 slider solve, because each of the 60 trajectory
- *     points became its own humanised sub-trajectory.
- *   - a caller on their own infrastructure, against their own fixtures, is
- *     paying for texture nobody is measuring.
- *
- * So the vocabulary of gestures is an INTERFACE and the humanisation is an
- * implementation of it. The solver says "tap here", "drag this there", "type
- * that"; a `Humanizer` decides what events that is and how long it takes.
- *
- * Four modes, selected by `CaptchaKrakenConfig.humanization`:
- *
- *     'mouse'   MouseHumanizer   — the default, and byte-for-byte what the
- *                                  driver did before this module existed.
- *     'mobile'  MobileHumanizer  — touch events, finger kinematics. Dispatches
- *                                  through a `TouchBackend`, so it drives either
- *                                  a Chromium-family page (CDP) or an
- *                                  Appium/WebdriverIO driver on a real device.
- *     'none'    NullHumanizer    — the shortest legal path to the same DOM
- *                                  effect.
- *     custom    anything satisfying `Humanizer`, passed as
- *                                  `CaptchaKrakenConfig.humanizer`.
- *
- * THE POINTER POSITION LIVES HERE, not in the solver. A humanizer that
- * dispatches no motion at all (mobile, between taps) still has to answer "where
- * is the pointer", because that is what the next gesture starts from and what
- * `SolveResult.finalMousePosition` reports.
+ * Pluggable because camoufox's juggler re-humanises every mouse.move() it is handed, and running
+ * both measured 82s against 13s on one GeeTest slider; and a touch widget needs touch events, not
+ * mousemove. See TRIBAL_KNOWLEDGE.md. The 2026-09 cut removed our drag-overshoot redraw and swipe
+ * wobble in favour of Cursory's raw recordings; the one-pixel tap wobble stayed because a
+ * motionless tap is a synthetic one.
  */
 import type { Page, PlaywrightElementHandle } from './playwright-types.js';
+import { HumanizationMode, PauseKind } from './kinds.js';
+export type { HumanizationMode, PauseKind } from './kinds.js';
 export type Point = [number, number];
-/**
- * Every inter-gesture wait the driver takes, named.
- *
- * A vocabulary rather than a number at each call site, because the whole point
- * of the mode switch is that these differ per device — a finger dwells on a tap
- * about four times as long as a mouse button is held, and neither number means
- * anything to the caller who turned humanisation off. Each mode supplies its own
- * table below; an unknown name yields no wait rather than throwing, so adding a
- * pause site cannot break a custom humanizer written against an older release.
- *
- *   tap      inside a click/tap, between press and release
- *   between  between two taps of one batch (grid tiles)
- *   grab     after pressing, before a drag starts moving
- *   drop     after a drag arrives, before releasing
- *   probe    between the slider's measurement nudges
- *   settle   before releasing a slider — the release IS the submit, and some
- *            vendors sample the final milliseconds of the gesture
- *   key      between two typed characters
- */
-export type PauseKind = 'tap' | 'between' | 'grab' | 'drop' | 'probe' | 'settle' | 'key';
+/** A recorded human movement morphed onto the endpoints; timings are cumulative ms. */
+export declare function trajectory(start: Point, end: Point, frequency: number): [Point[], number[]];
+/** Every inter-gesture wait the driver takes, named, so each device supplies its own table. */
 export declare const PAUSE_KINDS: readonly PauseKind[];
-/**
- * The gesture vocabulary the solver drives. Implement this to supply your own
- * humanisation; only `move`, `press`, `release`, `typeText` and `pause` are
- * required, and `BaseHumanizer` composes `click`/`drag` from them.
- */
 export interface Humanizer {
-    /** Mode name, for logs. */
     readonly name: string;
-    /**
-     * Whether this device has a cursor that can rest somewhere without touching.
-     * False switches off every hover-for-realism behaviour — the reCAPTCHA tile
-     * hover and the idle drift during inference — because on a touchscreen those
-     * are not weak mimicry, they are impossible.
-     */
+    /** False on a device with no resting cursor; switches off every hover-for-realism behaviour. */
     readonly hovers: boolean;
-    /** Where the pointer is now. */
     at: Point;
-    /** Called once at the top of each `solve()`. Drop per-page caches. */
     reset(page: Page): Promise<void>;
     move(page: Page, to: Point): Promise<void>;
     press(page: Page): Promise<void>;
@@ -96,7 +32,7 @@ export interface Humanizer {
     typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
     pause(kind: PauseKind): Promise<void>;
 }
-type PauseTable = Record<string, [number, number]>;
+type PauseTable = Partial<Record<PauseKind, [number, number]>>;
 export declare abstract class BaseHumanizer implements Humanizer {
     abstract readonly name: string;
     abstract readonly hovers: boolean;
@@ -108,190 +44,99 @@ export declare abstract class BaseHumanizer implements Humanizer {
     abstract press(page: Page): Promise<void>;
     abstract release(page: Page): Promise<void>;
     abstract typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
+    /** An unknown kind waits nothing, so adding a pause site cannot break a custom humanizer written against an older release. */
     protected pauseMs(kind: PauseKind): number;
     pause(kind: PauseKind): Promise<void>;
     click(page: Page, to: Point): Promise<void>;
     drag(page: Page, src: Point, dst: Point): Promise<void>;
 }
-/**
- * A hand on a mouse. Bezier arcs, Fitts's-law durations, overshoot.
- *
- * Everything in here was `solver.performSmoothMove` / `tracePath` before this
- * module existed, and is unchanged: the constants were measured and a refactor
- * is not the place to revisit them.
- */
 export declare class MouseHumanizer extends BaseHumanizer {
-    readonly name = "mouse";
+    readonly name: HumanizationMode;
     readonly hovers = true;
-    /** Inclusive ranges, in ms. See PauseKind. */
     protected readonly pauses: PauseTable;
     private frequency;
+    private viewportCache;
     constructor(start?: Point, frequency?: number);
+    reset(_page: Page): Promise<void>;
+    /** The window to keep the cursor inside; null under camoufox, which reports no viewport and whose window we ask instead. */
+    private viewport;
     move(page: Page, to: Point): Promise<void>;
     press(page: Page): Promise<void>;
     release(page: Page): Promise<void>;
+    /** Per character with a humanised pause, not type(text, {delay}): a constant inter-key delay is itself a signal these vendors score. */
     typeText(page: Page, _field: PlaywrightElementHandle, text: string): Promise<boolean>;
-    private trace;
 }
-/** `[x, y, dtMs]` — dt is the wait BEFORE that sample. */
+/** `[x, y, dtMs]`: dt is the wait before that sample. */
 export type TouchSample = [number, number, number];
-/**
- * Where touch events actually go.
- *
- * Three methods rather than one per sample, because the two backends want
- * opposite things: CDP dispatches one event per call and we pace it locally,
- * while a W3C/Appium driver takes a whole timed action chain in one round trip
- * and paces it on the device. Handing `move` the entire leg lets each do what it
- * is good at — and on a real device, pacing over the wire is not pacing at all.
- */
+/** Where touch events go. `move` takes a whole leg so a device driver can pace it itself. */
 export interface TouchBackend {
     readonly name: string;
     down(x: number, y: number): Promise<void>;
     move(path: TouchSample[]): Promise<void>;
     up(x: number, y: number): Promise<void>;
 }
-/**
- * `Input.dispatchTouchEvent` over a CDP session on a Playwright page.
- *
- * Chromium-family only, and that is checked at construction rather than
- * discovered per gesture: WebKit and Firefox (camoufox included) expose no touch
- * dispatch through Playwright at all, so the alternatives there are to fail
- * loudly or to quietly emit MOUSE events at a touch-only widget. The second is
- * worse than not running — the page's touch handlers never fire, the solve fails
- * for a reason nothing reports, and the report reads as a model that cannot
- * solve mobile puzzles.
- *
- * The context must also have been created with `hasTouch: true`, or the page
- * advertises no touch support to feature detection and a mobile widget renders
- * its desktop branch.
- */
+/** `Input.dispatchTouchEvent` over CDP; Chromium-family pages launched with `hasTouch: true`. */
 export declare class CdpTouchBackend implements TouchBackend {
-    readonly name = "cdp";
     private session;
+    readonly name = "cdp";
     private constructor();
+    /**
+     * Checked at construction, not per gesture. WebKit and Firefox expose no touch dispatch, and emitting
+     * mouse events instead is worse than not running: the page's touch handlers never fire and the report
+     * reads as a model that cannot solve mobile puzzles.
+     */
     static open(page: Page): Promise<CdpTouchBackend>;
     private send;
     down(x: number, y: number): Promise<void>;
     move(path: TouchSample[]): Promise<void>;
     up(_x: number, _y: number): Promise<void>;
 }
-/** CSS-pixel → device-pixel transform for a real handset. See AppiumTouchBackend. */
+/** CSS-pixel to device-pixel transform for a real handset. */
 export interface TouchTransform {
     scale?: number;
     origin?: Point;
 }
 /**
- * W3C pointer actions with `pointerType: 'touch'`, for Appium and WebdriverIO.
- *
- * Batches a whole leg into ONE action chain with per-sample durations, so the
- * kinematics are reproduced BY THE DEVICE rather than by a JS loop round-tripping
- * over the wire — over which a 90Hz path is not 90Hz at all.
- *
- * Press and release are separate `performActions()` calls on purpose. W3C input
- * state is per SESSION, so a pointer put down in one chain stays down across
- * later chains until it is lifted; that is what lets the puzzle-slider driver
- * press, screenshot, steer, screenshot and only then release. (It is also why
- * the spec has a "release actions" endpoint at all.)
- *
- * COORDINATES. Everything upstream of here is CSS pixels in the page's viewport,
- * because that is what `boundingBox()` returns. A real device wants screen
- * pixels, and the two differ by the device pixel ratio and by whatever chrome
- * sits above the webview. Neither is guessable from here, so both are options:
- *
- *     new AppiumTouchBackend(driver, { scale: 3, origin: [0, 132] })
- *
- * `scale` is usually `window.devicePixelRatio`; `origin` is the top-left of the
- * webview in screen coordinates. Defaults are the identity transform, which is
- * correct for browser mobile emulation and for any caller who has already mapped
- * the coordinates themselves.
+ * W3C touch pointer actions for Appium and WebdriverIO, paced by the device from one chain per leg.
+ * Raw protocol payloads so this imports no client. Press and release are separate performs because W3C
+ * input state is per session: that is what lets the slider driver press, screenshot, steer, then release.
  */
 export declare class AppiumTouchBackend implements TouchBackend {
-    readonly name = "appium";
     private driver;
+    private page?;
+    readonly name = "appium";
     private scale;
     private origin;
-    /**
-     * UNSET is not the same fact as an explicit 1. The first is a caller who has
-     * not thought about the transform; the second is one who has, and says the
-     * coordinates are already mapped. Only the first is checked.
-     */
     private scaleGiven;
-    private page;
     private checked;
-    constructor(driver: any, transform?: TouchTransform, page?: Page);
+    constructor(driver: any, transform?: TouchTransform, page?: Page | undefined);
     /**
-     * Refuse an unset scale on a session that reports it is not 1.
-     *
-     * A wrong transform fails SILENTLY on both sides of the wire: the chain is
-     * valid W3C, the device performs it, and the finger lands somewhere else. The
-     * solve then fails looking exactly like a model that cannot read the puzzle.
-     *
-     * Read once, not per gesture — it is a round trip into the page and a solve
-     * makes hundreds of these. An unreadable ratio is absent evidence, not
-     * evidence of a mismatch, so it falls through to the identity. `origin`
-     * cannot be measured from here at all, so it is named in the refusal rather
-     * than guessed at.
+     * Refuse an unset scale on a device whose pixel ratio is not 1: the finger would land elsewhere. An
+     * explicit scale of 1 is the caller's word and is not re-checked; the ratio is read once, since a solve
+     * makes hundreds of these, and an unreadable ratio is taken as 1.
      */
     private checkScale;
     private map;
-    /**
-     * One W3C action chain on a single touch pointer.
-     *
-     * Sent as the raw protocol payload rather than through a client's action
-     * builder, so this imports nothing and works against any client that speaks
-     * WebDriver — WebdriverIO (`performActions`), selenium-webdriver, or a thin
-     * HTTP wrapper of someone's own.
-     */
     private perform;
     down(x: number, y: number): Promise<void>;
+    /** The per-sample gap becomes the move's `duration`, so the device interpolates the leg itself. */
     move(path: TouchSample[]): Promise<void>;
     up(_x: number, _y: number): Promise<void>;
 }
-/**
- * Playwright's `page.touchscreen.tap()` — taps only, no travel.
- *
- * The fallback for a browser with touch support but no CDP (WebKit). A tap still
- * lands correctly; a DRAG cannot be expressed at all, so it throws rather than
- * approximating one with a mouse, for the reason in `CdpTouchBackend`.
- */
+/** Playwright's tap-only touchscreen, for browsers with touch but no CDP. A drag cannot be expressed. */
 export declare class TouchscreenTouchBackend implements TouchBackend {
-    readonly name = "touchscreen";
     private page;
+    readonly name = "touchscreen";
     private pending;
-    constructor(page: Page);
+    constructor(page: any);
     down(x: number, y: number): Promise<void>;
     move(_path: TouchSample[]): Promise<void>;
     up(x: number, y: number): Promise<void>;
 }
-/**
- * Pick a backend. An explicit `driver` always wins.
- *
- * `driver` is what a caller passes when the thing under automation is not the
- * thing being touched — an Appium session driving a real handset while the page
- * object is a webview bridge over it.
- */
 export declare function touchBackendFor(page: Page, driver?: any, transform?: TouchTransform): Promise<TouchBackend>;
-/**
- * A finger on glass.
- *
- * What differs from `MouseHumanizer`, and none of it is cosmetic:
- *
- *   - **A move that is not touching dispatches nothing.** There is no hover on a
- *     touchscreen. The position is still RECORDED, because the next gesture
- *     starts from it, but no event is emitted — emitting one would be the
- *     desktop tell this mode exists to remove.
- *   - **Taps carry a contact wobble.** A finger held on glass for 90ms does not
- *     report one unchanging coordinate; the centroid of the contact patch rolls
- *     a pixel or two under pressure. A tap with zero movement between touchstart
- *     and touchend is a synthetic tap.
- *   - **Touch kinematics**, via `generate_swipe` — see its docstring for why that
- *     is a different model rather than the mouse one retuned.
- *   - **Longer, more variable pauses.** Every measured touch interaction is
- *     slower than its mouse equivalent, and a phone's are more variable because
- *     the hand holding the device is also moving.
- */
+/** A finger on glass: no hover, touch events only, slower and more variable pauses. */
 export declare class MobileHumanizer extends BaseHumanizer {
-    readonly name = "mobile";
+    readonly name: HumanizationMode;
     readonly hovers = false;
     protected readonly pauses: PauseTable;
     private backend;
@@ -305,37 +150,23 @@ export declare class MobileHumanizer extends BaseHumanizer {
         transform?: TouchTransform;
         frequency?: number;
     });
+    /** A solve that ended mid-gesture leaves a pointer down in the session's input state; lift it before the next one. */
     reset(page: Page): Promise<void>;
     private touch;
     move(page: Page, to: Point): Promise<void>;
     press(page: Page): Promise<void>;
     release(page: Page): Promise<void>;
-    /** Tap. The wobble is the point — see the class docstring. */
+    /** A tap whose contact patch wobbles a pixel while held; a motionless tap is a synthetic one. */
     click(page: Page, to: Point): Promise<void>;
-    /**
-     * Into the field, at soft-keyboard pace.
-     *
-     * The mouse path clears with Control+A. There is no Control on a phone
-     * keyboard, so the box is cleared through the element instead — which also
-     * works on an Appium element, where `page.keyboard` does not exist.
-     */
+    /** Clears through the element: there is no Control key on a phone and no `page.keyboard` on Appium. */
     typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
 }
 /**
- * No humanisation: the shortest legal path to the same DOM effect.
- *
- * One mousemove per gesture instead of sixty, no dwell, no jitter, and text goes
- * in with a single `fill()`. Roughly an order of magnitude faster on a slider
- * puzzle, and it will be detected by anything that scores pointer telemetry —
- * which is the whole trade, stated plainly. For fixtures, for self-hosted
- * targets, and for callers whose stack humanises somewhere else.
- *
- * Still moves the mouse and still presses and releases: the events are what make
- * the widget respond at all, and a click dispatched with no preceding move fails
- * on the vendors that require a hover state first.
+ * No humanisation: one move per gesture and a single fill. Fast, and detectable. It still moves before
+ * it presses, because a click with no preceding move fails on the vendors that require a hover state first.
  */
 export declare class NullHumanizer extends BaseHumanizer {
-    readonly name = "none";
+    readonly name: HumanizationMode;
     readonly hovers = false;
     protected readonly pauses: PauseTable;
     move(page: Page, to: Point): Promise<void>;
@@ -343,9 +174,7 @@ export declare class NullHumanizer extends BaseHumanizer {
     release(page: Page): Promise<void>;
     typeText(page: Page, field: PlaywrightElementHandle, text: string): Promise<boolean>;
 }
-export type HumanizationMode = 'mouse' | 'mobile' | 'none';
 export declare const MODES: readonly HumanizationMode[];
-/** The subset of `CaptchaKrakenConfig` this module reads. */
 export interface HumanizerOptions {
     humanization?: HumanizationMode;
     humanizer?: Humanizer;
@@ -357,21 +186,8 @@ export interface HumanizerOptions {
     };
 }
 /**
- * The humanizer one solver will use, from its config.
- *
- * Precedence, and the reasoning for it:
- *
- *   1. `config.humanizer` — a caller who handed us an OBJECT has already
- *      decided; there is nothing left to select.
- *   2. `config.humanization` — an explicit mode set in code.
- *   3. `CAPTCHA_HUMANIZATION` — for a caller who cannot edit the code.
- *   4. 'mouse'.
- *
- * Note that the env var loses to code, which is the opposite of this package's
- * model-identity settings. Deliberate: which mode is right is a property of the
- * PAGE the caller is driving, and an env var flipping a desktop solve to touch
- * dispatch would break every one of them silently. Pinning a model is a
- * deployment decision; picking an input device is not.
+ * `config.humanizer`, else `config.humanization`, else CAPTCHA_HUMANIZATION, else mouse. The env var loses
+ * to code, the opposite of the model settings, on purpose: an env var flipping a desktop solve to touch
+ * dispatch would break every one of them silently.
  */
 export declare function resolveHumanizer(config?: HumanizerOptions): Humanizer;
-export {};