captchakraken 2.9.0 → 3.0.0

package/dist/humanize.js

@@ -1,90 +1,48 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MODES = exports.NullHumanizer = exports.MobileHumanizer = exports.TouchscreenTouchBackend = exports.AppiumTouchBackend = exports.CdpTouchBackend = exports.MouseHumanizer = exports.BaseHumanizer = exports.PAUSE_KINDS = void 0;
+exports.trajectory = trajectory;
 exports.touchBackendFor = touchBackendFor;
 exports.resolveHumanizer = resolveHumanizer;
-const trajectory_js_1 = require("./trajectory.js");
+const cursory_js_1 = require("cursory-js");
+const kinds_js_1 = require("./kinds.js");
 const delay = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
 const log = (m) => console.log(`[captchakraken] ${m}`);
 const uniform = (lo, hi) => lo + Math.random() * (hi - lo);
-/**
- * A move to where the pointer already is emits nothing.
- *
- * `moveAndClick` travels to the element and THEN clicks at the point it landed
- * on, so without this every click would dispatch one redundant move at the
- * coordinate the trajectory just finished on.
- */
+// moveAndClick clicks at the landing point; without this every click would dispatch one redundant move.
 const samePoint = (a, b) => Math.abs(a[0] - b[0]) < 1e-6 && Math.abs(a[1] - b[1]) < 1e-6;
-/** Box-Muller, as in trajectory.ts — the contact wobble wants a normal deviate. */
-function gauss(mu, sigma) {
+const gauss = (sigma) => {
     let u = 0;
     while (u === 0)
         u = Math.random();
-    const v = Math.random();
-    return mu + sigma * Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+    return sigma * Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * Math.random());
+};
+const closedError = (e) => /Target closed|Session closed/.test(e instanceof Error ? e.message : String(e));
+/** A recorded human movement morphed onto the endpoints; timings are cumulative ms. */
+function trajectory(start, end, frequency) {
+    const { points, timings } = (0, cursory_js_1.generateTrajectory)(start, end, { frequency });
+    return [points.map((q) => [Number(q[0]), Number(q[1])]), timings.map(Number)];
 }
-exports.PAUSE_KINDS = [
-    'tap',
-    'between',
-    'grab',
-    'drop',
-    'probe',
-    'settle',
-    'key',
-];
+/** Every inter-gesture wait the driver takes, named, so each device supplies its own table. */
+exports.PAUSE_KINDS = Object.values(kinds_js_1.PauseKind);
 class BaseHumanizer {
     constructor(start = [0, 0]) {
         this.at = [Number(start[0]), Number(start[1])];
     }
     async reset(_page) { }
+    /** An unknown kind waits nothing, so adding a pause site cannot break a custom humanizer written against an older release. */
     pauseMs(kind) {
         const range = this.pauses[kind];
         return range ? uniform(range[0], range[1]) : 0;
@@ -95,68 +53,86 @@ class BaseHumanizer {
     async click(page, to) {
         await this.move(page, to);
         await this.press(page);
-        await this.pause('tap');
+        await this.pause(kinds_js_1.PauseKind.TAP);
         await this.release(page);
     }
     async drag(page, src, dst) {
         await this.move(page, src);
         await this.press(page);
-        await this.pause('grab');
+        await this.pause(kinds_js_1.PauseKind.GRAB);
         await this.move(page, dst);
-        await this.pause('drop');
+        await this.pause(kinds_js_1.PauseKind.DROP);
         await this.release(page);
     }
 }
 exports.BaseHumanizer = BaseHumanizer;
-// ───────────────────────────────────────────────────────────────────── mouse
-/**
- * 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.
- */
 class MouseHumanizer extends BaseHumanizer {
     constructor(start = [0, 0], frequency = 60) {
         super(start);
-        this.name = 'mouse';
+        this.name = kinds_js_1.HumanizationMode.MOUSE;
         this.hovers = true;
-        /** Inclusive ranges, in ms. See PauseKind. */
         this.pauses = {
-            tap: [20, 50],
-            between: [80, 160],
-            grab: [50, 100],
-            drop: [50, 100],
-            probe: [40, 80],
-            settle: [90, 210],
-            key: [45, 135],
+            tap: [20, 50], between: [80, 160], grab: [50, 100], drop: [50, 100],
+            probe: [40, 80], settle: [90, 210], key: [45, 135],
         };
         this.frequency = frequency;
     }
+    async reset(_page) { this.viewportCache = undefined; }
+    /** The window to keep the cursor inside; null under camoufox, which reports no viewport and whose window we ask instead. */
+    async viewport(page) {
+        if (this.viewportCache !== undefined)
+            return this.viewportCache;
+        this.viewportCache = null;
+        const reads = [
+            () => page.viewportSize(),
+            () => page.evaluate ? page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight })) : null,
+        ];
+        for (const read of reads) {
+            try {
+                const vp = await read();
+                if (vp && vp.width && vp.height) {
+                    this.viewportCache = { width: vp.width, height: vp.height };
+                    break;
+                }
+            }
+            catch { /* try the next read */ }
+        }
+        return this.viewportCache;
+    }
     async move(page, to) {
         if (samePoint(this.at, to))
             return;
-        const [points, timings] = (0, trajectory_js_1.generate_trajectory)(this.at, to, this.frequency);
-        await this.trace(page, points, timings);
-    }
-    async press(page) {
-        await page.mouse.down();
-    }
-    async release(page) {
-        await page.mouse.up();
+        const [points, timings] = trajectory(this.at, to, this.frequency);
+        // Clamp only when the viewport is known: a coordinate pinned to the edge of a guessed one deadlocks camoufox's juggler (upstream #225).
+        const viewport = await this.viewport(page);
+        const startTime = Date.now();
+        for (let i = 0; i < points.length; i++) {
+            const cx = viewport ? Math.max(1, Math.min(points[i][0], viewport.width - 1)) : points[i][0];
+            const cy = viewport ? Math.max(1, Math.min(points[i][1], viewport.height - 1)) : points[i][1];
+            try {
+                await page.mouse.move(cx, cy);
+            }
+            catch (e) {
+                if (closedError(e)) {
+                    log('could not move mouse; page or session closed');
+                    return;
+                }
+                continue;
+            }
+            this.at = [cx, cy];
+            if (timings[i] !== undefined)
+                await delay(startTime + timings[i] - Date.now());
+        }
     }
+    async press(page) { await page.mouse.down(); }
+    async release(page) { await page.mouse.up(); }
+    /** Per character with a humanised pause, not type(text, {delay}): a constant inter-key delay is itself a signal these vendors score. */
     async typeText(page, _field, text) {
-        // A retry round arrives with the previous attempt still in the box, and
-        // typing would APPEND to it — submitting a string the model never read.
+        // Clear first: a retry round arrives with the previous attempt still in the box, and typing would append.
         try {
             await page.keyboard.press('Control+A');
         }
-        catch {
-            /* not every field supports it; the type below still replaces on most */
-        }
-        // Per character rather than one `type(text, {delay})` call: a constant
-        // inter-key delay is itself a signal, and these are the vendors that score
-        // typing cadence.
+        catch { /* the type below still replaces on most */ }
         for (const ch of text) {
             try {
                 await page.keyboard.type(ch);
@@ -165,76 +141,26 @@ class MouseHumanizer extends BaseHumanizer {
                 log(`could not type into the captcha field: ${e}`);
                 return false;
             }
-            await this.pause('key');
+            await this.pause(kinds_js_1.PauseKind.KEY);
         }
         return true;
     }
-    async trace(page, points, timings) {
-        // KNOWN DIVERGENCE from the Python port, carried over unchanged rather than
-        // fixed inside a refactor. Python clamps only when the viewport is actually
-        // known, because camoufox reports `viewportSize` null and a coordinate
-        // pinned to the edge of a GUESSED viewport is what deadlocks its humanised-
-        // mouse juggler (upstream #225) — see MouseHumanizer._viewport there. This
-        // port still assumes 1920x1080. Worth fixing on its own, with its own test.
-        let viewport = { width: 1920, height: 1080 };
-        try {
-            const vp = page.viewportSize();
-            if (vp)
-                viewport = vp;
-        }
-        catch {
-            /* keep the default */
-        }
-        const startTime = Date.now();
-        for (let i = 0; i < points.length; i++) {
-            try {
-                const cx = Math.max(0, Math.min(points[i][0], viewport.width));
-                const cy = Math.max(0, Math.min(points[i][1], viewport.height));
-                await page.mouse.move(cx, cy);
-                this.at = [cx, cy];
-                if (timings[i] !== undefined) {
-                    const wait = startTime + timings[i] - Date.now();
-                    if (wait > 0)
-                        await delay(wait);
-                }
-            }
-            catch (error) {
-                const msg = error instanceof Error ? error.message : String(error);
-                if (msg.includes('Target closed') || msg.includes('Session closed')) {
-                    log('Warning: could not move mouse, page or session closed.');
-                    return;
-                }
-                // Any other per-sample failure is skipped rather than fatal — losing
-                // one mousemove must not lose the solve.
-            }
-        }
-    }
 }
 exports.MouseHumanizer = MouseHumanizer;
-/**
- * `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`. */
 class CdpTouchBackend {
     constructor(session) {
-        this.name = 'cdp';
         this.session = session;
+        this.name = 'cdp';
     }
+    /**
+     * 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 async open(page) {
         try {
-            const context = page.context();
-            return new CdpTouchBackend(await context.newCDPSession(page));
+            return new CdpTouchBackend(await page.context().newCDPSession(page));
         }
         catch (e) {
             throw new Error(`mobile humanisation needs touch dispatch, and this page offers none (${e}). ` +
@@ -243,24 +169,15 @@ class CdpTouchBackend {
         }
     }
     async send(kind, points) {
+        // radius and force are what a real digitizer reports; a synthetic tap reports zero.
         await this.session.send('Input.dispatchTouchEvent', {
             type: kind,
             touchPoints: points.map(([x, y]) => ({
-                // radiusX/Y and force are what a real digitizer reports and a synthetic
-                // tap does not. A vendor reading `Touch.radiusX === 0` has a free bot
-                // signal otherwise.
-                x,
-                y,
-                radiusX: uniform(8, 14),
-                radiusY: uniform(8, 14),
-                force: uniform(0.35, 0.75),
-                id: 1,
+                x, y, radiusX: uniform(8, 14), radiusY: uniform(8, 14), force: uniform(0.35, 0.75), id: 1,
             })),
         });
     }
-    async down(x, y) {
-        await this.send('touchStart', [[x, y]]);
-    }
+    async down(x, y) { await this.send('touchStart', [[x, y]]); }
     async move(path) {
         for (const [x, y, dt] of path) {
             if (dt > 0)
@@ -268,61 +185,28 @@ class CdpTouchBackend {
             await this.send('touchMove', [[x, y]]);
         }
     }
-    async up(_x, _y) {
-        // touchEnd carries no touchPoints: the point being lifted is identified by
-        // its absence, which is what the protocol says and what a real release
-        // looks like.
-        await this.send('touchEnd', []);
-    }
+    async up(_x, _y) { await this.send('touchEnd', []); }
 }
 exports.CdpTouchBackend = CdpTouchBackend;
 /**
- * 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.
  */
 class AppiumTouchBackend {
     constructor(driver, transform = {}, page) {
+        this.driver = driver;
+        this.page = page;
         this.name = 'appium';
         this.checked = false;
-        this.driver = driver;
         this.scaleGiven = transform.scale !== undefined;
         this.scale = transform.scale ?? 1;
         this.origin = transform.origin ?? [0, 0];
-        this.page = page;
     }
     /**
-     * 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.
      */
     async checkScale() {
         this.checked = true;
@@ -333,51 +217,23 @@ class AppiumTouchBackend {
             dpr = Number(await this.page.evaluate('() => window.devicePixelRatio'));
         }
         catch {
-            return; // cannot measure is not a mismatch
+            return;
         }
         if (!Number.isFinite(dpr) || Math.abs(dpr - 1) < 1e-6)
             return;
-        throw new Error(`the touch driver maps CSS pixels onto a device reporting devicePixelRatio ` +
-            `${dpr}, and no scale was given. Every gesture would land at ` +
-            `${(1 / dpr).toFixed(2)}x the intended offset, and nothing would report it — ` +
-            `the chain is valid, the device performs it, and the solve fails looking ` +
-            `like a weak model.\n` +
-            `  Fix: touchTransform: { scale: ${dpr}, origin: [x, y] }, where origin is ` +
-            `the webview's top-left in SCREEN coordinates. That half cannot be measured ` +
-            `from here.\n` +
-            `  Or pass scale: 1 to assert the coordinates are already mapped.`);
+        throw new Error(`the touch driver maps CSS pixels onto a device reporting devicePixelRatio ${dpr}, and no scale ` +
+            `was given. Fix: touchTransform: { scale: ${dpr}, origin: [x, y] }, where origin is the webview's ` +
+            'top-left in SCREEN coordinates, or pass scale: 1 to assert the coordinates are already mapped.');
     }
     map(x, y) {
-        return [
-            Math.round(this.origin[0] + x * this.scale),
-            Math.round(this.origin[1] + y * this.scale),
-        ];
+        return [Math.round(this.origin[0] + x * this.scale), Math.round(this.origin[1] + y * this.scale)];
     }
-    /**
-     * 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.
-     */
     async perform(actions) {
-        const chain = [
-            {
-                type: 'pointer',
-                id: 'ck-finger',
-                parameters: { pointerType: 'touch' },
-                actions,
-            },
-        ];
-        if (typeof this.driver.performActions === 'function') {
-            await this.driver.performActions(chain);
-            return;
-        }
-        if (typeof this.driver.execute === 'function') {
-            await this.driver.execute('actions', { actions: chain });
-            return;
-        }
+        const chain = [{ type: 'pointer', id: 'ck-finger', parameters: { pointerType: 'touch' }, actions }];
+        if (typeof this.driver.performActions === 'function')
+            return this.driver.performActions(chain);
+        if (typeof this.driver.execute === 'function')
+            return this.driver.execute('actions', { actions: chain });
         throw new Error("the touch driver speaks neither performActions() nor execute('actions', …); " +
             'pass a WebDriver-compatible driver or a custom TouchBackend.');
     }
@@ -390,6 +246,7 @@ class AppiumTouchBackend {
             { type: 'pointerDown', button: 0 },
         ]);
     }
+    /** The per-sample gap becomes the move's `duration`, so the device interpolates the leg itself. */
     async move(path) {
         if (!this.checked)
             await this.checkScale();
@@ -397,10 +254,6 @@ class AppiumTouchBackend {
             return;
         await this.perform(path.map(([x, y, dt]) => {
             const [mx, my] = this.map(x, y);
-            // The per-sample gap becomes the move's DURATION, not a pause before it:
-            // the device then interpolates over that window and reports intermediate
-            // samples of its own, which is what a finger sliding across a digitizer
-            // actually produces.
             return { type: 'pointerMove', duration: Math.max(0, Math.round(dt)), origin: 'viewport', x: mx, y: my };
         }));
     }
@@ -411,26 +264,17 @@ class AppiumTouchBackend {
     }
 }
 exports.AppiumTouchBackend = AppiumTouchBackend;
-/**
- * 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. */
 class TouchscreenTouchBackend {
     constructor(page) {
+        this.page = page;
         this.name = 'touchscreen';
         this.pending = null;
-        this.page = page;
-    }
-    async down(x, y) {
-        this.pending = [x, y];
     }
+    async down(x, y) { this.pending = [x, y]; }
     async move(_path) {
-        throw new Error('this browser exposes taps but not touch travel, so a drag/slide puzzle ' +
-            'cannot be driven on it. Use a Chromium-family browser (CDP touch dispatch) ' +
-            'or an Appium driver.');
+        throw new Error('this browser exposes taps but not touch travel, so a drag/slide puzzle cannot be ' +
+            'driven on it. Use a Chromium-family browser (CDP touch dispatch) or an Appium driver.');
     }
     async up(x, y) {
         const at = this.pending ?? [x, y];
@@ -439,19 +283,10 @@ class TouchscreenTouchBackend {
     }
 }
 exports.TouchscreenTouchBackend = TouchscreenTouchBackend;
-/**
- * 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.
- */
 async function touchBackendFor(page, driver, transform) {
     if (driver) {
-        if (typeof driver.down === 'function' && typeof driver.up === 'function') {
+        if (typeof driver.down === 'function' && typeof driver.up === 'function')
             return driver;
-        }
-        // The page comes along so the backend can ask what it is mapping ONTO.
         return new AppiumTouchBackend(driver, transform, page);
     }
     try {
@@ -465,43 +300,16 @@ async function touchBackendFor(page, driver, transform) {
         throw e;
     }
 }
-// ──────────────────────────────────────────────────────────────────── mobile
-/**
- * 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. */
 class MobileHumanizer extends BaseHumanizer {
     constructor(start = [0, 0], options = {}) {
         super(start);
-        this.name = 'mobile';
+        this.name = kinds_js_1.HumanizationMode.MOBILE;
         this.hovers = false;
+        // tap: measured human touch dwell clusters at 60-120ms. key: a soft keyboard is ~3x slower than a physical one.
         this.pauses = {
-            // A tap's press-to-release. Measured human touch dwell clusters at
-            // 60-120ms; a synthesised one is usually 0.
-            tap: [55, 130],
-            between: [140, 320],
-            grab: [90, 190],
-            drop: [80, 170],
-            probe: [70, 140],
-            settle: [140, 300],
-            // Soft-keyboard typing, which is ~3x slower than a physical keyboard and
-            // much more variable.
-            key: [110, 320],
+            tap: [55, 130], between: [140, 320], grab: [90, 190], drop: [80, 170],
+            probe: [70, 140], settle: [140, 300], key: [110, 320],
         };
         this.down = false;
         this.backend = options.backend ?? null;
@@ -509,40 +317,27 @@ class MobileHumanizer extends BaseHumanizer {
         this.transform = options.transform;
         this.frequency = options.frequency ?? 90;
     }
+    /** A solve that ended mid-gesture leaves a pointer down in the session's input state; lift it before the next one. */
     async reset(page) {
-        // A solve that ended mid-gesture (a timeout inside the slider) leaves a
-        // pointer down in the SESSION's input state, and the next chain would then
-        // start from a finger already on the glass. Lift it.
-        if (this.down) {
-            try {
-                await (await this.touch(page)).up(this.at[0], this.at[1]);
-            }
-            catch {
-                /* best effort; a stale pointer must not fail a solve */
-            }
-            this.down = false;
+        if (!this.down)
+            return;
+        try {
+            await (await this.touch(page)).up(this.at[0], this.at[1]);
         }
+        catch { /* a stale pointer must not fail a solve */ }
+        this.down = false;
     }
     async touch(page) {
-        if (!this.backend) {
+        if (!this.backend)
             this.backend = await touchBackendFor(page, this.driver, this.transform);
-        }
         return this.backend;
     }
     async move(page, to) {
         const dest = [Number(to[0]), Number(to[1])];
-        if (!this.down) {
-            // No contact, no events. Just remember where the next touch lands.
-            this.at = dest;
-            return;
+        if (this.down) {
+            const [points, timings] = trajectory(this.at, dest, this.frequency);
+            await (await this.touch(page)).move(points.map(([x, y], i) => [x, y, timings[i] - (i ? timings[i - 1] : 0)]));
         }
-        const [points, timings] = (0, trajectory_js_1.generate_swipe)(this.at, dest, this.frequency);
-        const path = points.map(([x, y], i) => [
-            x,
-            y,
-            timings[i] - (i ? timings[i - 1] : 0),
-        ]);
-        await (await this.touch(page)).move(path);
         this.at = dest;
     }
     async press(page) {
@@ -553,30 +348,20 @@ class MobileHumanizer extends BaseHumanizer {
         await (await this.touch(page)).up(this.at[0], this.at[1]);
         this.down = false;
     }
-    /** 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. */
     async click(page, to) {
         await this.move(page, to);
         await this.press(page);
-        const held = this.pauseMs('tap');
+        const held = this.pauseMs(kinds_js_1.PauseKind.TAP);
         await delay(held / 2);
         try {
-            await (await this.touch(page)).move([
-                [this.at[0] + gauss(0, 0.9), this.at[1] + gauss(0, 0.9), 0],
-            ]);
-        }
-        catch {
-            /* a tap-only backend cannot wobble; the tap still lands */
+            await (await this.touch(page)).move([[this.at[0] + gauss(0.9), this.at[1] + gauss(0.9), 0]]);
         }
+        catch { /* a tap-only backend cannot wobble; the tap still lands */ }
         await delay(held / 2);
         await this.release(page);
     }
-    /**
-     * 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. */
     async typeText(page, field, text) {
         const f = field;
         for (const [name, arg] of [['clear', undefined], ['fill', '']]) {
@@ -586,45 +371,33 @@ class MobileHumanizer extends BaseHumanizer {
                 await f[name](arg);
                 break;
             }
-            catch {
-                /* an uncleared box is recoverable; a crash is not */
-            }
+            catch { /* an uncleared box is recoverable */ }
         }
         for (const ch of text) {
             try {
                 if (typeof f?.sendKeys === 'function')
-                    await f.sendKeys(ch); // Appium / WebDriver
+                    await f.sendKeys(ch);
                 else
-                    await page.keyboard.type(ch); // mobile emulation
+                    await page.keyboard.type(ch);
             }
             catch (e) {
                 log(`could not type into the captcha field: ${e}`);
                 return false;
             }
-            await this.pause('key');
+            await this.pause(kinds_js_1.PauseKind.KEY);
         }
         return true;
     }
 }
 exports.MobileHumanizer = MobileHumanizer;
-// ────────────────────────────────────────────────────────────────────── none
 /**
- * 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.
  */
 class NullHumanizer extends BaseHumanizer {
     constructor() {
         super(...arguments);
-        this.name = 'none';
+        this.name = kinds_js_1.HumanizationMode.NONE;
         this.hovers = false;
         this.pauses = {};
     }
@@ -636,32 +409,22 @@ class NullHumanizer extends BaseHumanizer {
             await page.mouse.move(this.at[0], this.at[1]);
         }
         catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            if (msg.includes('Target closed') || msg.includes('Session closed')) {
-                log('Warning: could not move mouse, page or session closed.');
-            }
+            if (closedError(e))
+                log('could not move mouse; page or session closed');
         }
     }
-    async press(page) {
-        await page.mouse.down();
-    }
-    async release(page) {
-        await page.mouse.up();
-    }
+    async press(page) { await page.mouse.down(); }
+    async release(page) { await page.mouse.up(); }
     async typeText(page, field, text) {
         try {
-            await field.fill(text); // replaces, so no Control+A round is needed
+            await field.fill(text);
             return true;
         }
-        catch {
-            /* fall through to the keyboard */
-        }
+        catch { /* fall through to the keyboard */ }
         try {
             await page.keyboard.press('Control+A');
         }
-        catch {
-            /* optional */
-        }
+        catch { /* optional */ }
         try {
             await page.keyboard.type(text);
             return true;
@@ -673,44 +436,25 @@ class NullHumanizer extends BaseHumanizer {
     }
 }
 exports.NullHumanizer = NullHumanizer;
-exports.MODES = ['mouse', 'mobile', 'none'];
+exports.MODES = Object.values(kinds_js_1.HumanizationMode);
 /**
- * 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.
  */
 function resolveHumanizer(config = {}) {
     if (config.humanizer)
         return config.humanizer;
-    const raw = (config.humanization ?? process.env.CAPTCHA_HUMANIZATION ?? 'mouse')
-        .toString()
-        .trim()
-        .toLowerCase();
-    if (!exports.MODES.includes(raw)) {
+    const raw = (config.humanization ?? process.env.CAPTCHA_HUMANIZATION ?? kinds_js_1.HumanizationMode.MOUSE).toString().trim().toLowerCase();
+    if (!(0, kinds_js_1.isOneOf)(kinds_js_1.HumanizationMode, raw)) {
         throw new Error(`unknown humanization mode '${raw}'; expected one of ${exports.MODES.join(', ')}, ` +
             'or pass your own object as CaptchaKrakenConfig.humanizer');
     }
     const p = config.startingMousePosition;
     const start = p ? [p.x, p.y] : [0, 0];
-    if (raw === 'mobile') {
-        return new MobileHumanizer(start, {
-            driver: config.touchDriver,
-            transform: config.touchTransform,
-        });
-    }
-    if (raw === 'none')
+    if (raw === kinds_js_1.HumanizationMode.MOBILE)
+        return new MobileHumanizer(start, { driver: config.touchDriver, transform: config.touchTransform });
+    if (raw === kinds_js_1.HumanizationMode.NONE)
         return new NullHumanizer(start);
     return new MouseHumanizer(start);
 }