captchakraken 2.4.0 → 2.6.0

package/dist/puppeteer-adapter.js

@@ -15,6 +15,7 @@
  *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
  *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
  *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
+ *   - `page.isClosed()`                → same, but must be forwarded explicitly
  * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
  * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
  * call-compatible and passed straight through.
@@ -62,6 +63,7 @@ function wrapHandle(h) {
         getAttribute: (name) => h.evaluate((el, n) => el.getAttribute(n), name),
         isVisible: () => h.isVisible(),
         textContent: () => h.evaluate((el) => el.textContent),
+        $: async (selector) => wrapHandle(await h.$(selector)),
     };
 }
 function wrapFrame(f) {
@@ -86,11 +88,32 @@ function fromPuppeteer(page) {
             down: (options) => page.mouse.down(options),
             up: (options) => page.mouse.up(options),
         },
+        keyboard: {
+            type: (text, options) => page.keyboard.type(text, options),
+            // Puppeteer has no combo syntax: 'Control+A' must be held, pressed,
+            // released. Playwright accepts the combo string directly, which is why
+            // the solver speaks Playwright and this adapter translates.
+            press: async (key) => {
+                const parts = key.split('+');
+                const target = parts.pop();
+                for (const mod of parts)
+                    await page.keyboard.down(mod);
+                await page.keyboard.press(target);
+                for (const mod of parts.reverse())
+                    await page.keyboard.up(mod);
+            },
+        },
         waitForTimeout: (timeout) => new Promise((resolve) => setTimeout(resolve, timeout)),
         waitForSelector: async (selector, options) => wrapHandle(await page.waitForSelector(selector, toPuppeteerSelectorOptions(options))),
         viewportSize: () => page.viewport(),
         $: async (selector) => wrapHandle(await page.$(selector)),
         $$: async (selector) => (await page.$$(selector)).map((h) => wrapHandle(h)).filter(Boolean),
         $eval: (selector, pageFunction, arg) => page.$eval(selector, pageFunction, arg),
+        // Same name and shape on both libraries, but it still has to be forwarded:
+        // the wrapper is a fresh object literal, so anything not listed here is
+        // simply absent. The auto-solve watcher reads it to end its loop when the
+        // caller closes the browser, and an undefined `isClosed` reads as "still
+        // open" — a watcher that polls a dead page forever.
+        isClosed: () => page.isClosed(),
     };
 }

package/dist/python-command.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which interpreter runs the bundled CaptchaKraken CLI.
+ *
+ * This used to be `pythonCommand = 'python'`, inline in solver.ts. On
+ * Debian/Ubuntu — the most common Linux deployment target, and what CI runs —
+ * there is no `python` on PATH at all, only `python3`. So every JS solve died
+ * with `/bin/sh: 1: python: not found` before it ever reached the model, unless
+ * a `.venv` happened to exist next to the package. The type doc claimed the
+ * default was "'python' or 'python3'"; the code never tried `python3`.
+ *
+ * That is a straight violation of the rule that the Python and JS clients
+ * behave identically: the Python client obviously ran, so the divergence looked
+ * like a model or endpoint problem rather than a missing binary.
+ *
+ * Kept in its own module, with the probe injected, so the resolution order is
+ * testable without spawning anything.
+ */
+/** Env var that overrides everything below it. */
+export declare const PYTHON_ENV_VAR = "CAPTCHA_KRAKEN_PYTHON";
+/**
+ * Candidates tried in order when nothing is configured.
+ *
+ * `python3` FIRST. On Debian-family systems `python` is absent; where both
+ * exist they are the same interpreter in practice, and PEP 394 makes `python3`
+ * the portable spelling. `python` stays as the fallback for Windows and for
+ * venvs that only expose the unsuffixed name.
+ */
+export declare const PYTHON_CANDIDATES: readonly ["python3", "python"];
+export interface ResolveOptions {
+    /** `config.pythonCommand`, if the caller set one. Wins outright. */
+    configured?: string;
+    /** The venv interpreter, when one was found next to the CLI. Wins over probing. */
+    venvPython?: string | null;
+    /** Process env, injected for testability. */
+    env?: NodeJS.ProcessEnv;
+    /** Returns true if the command is runnable. Injected so tests never spawn. */
+    exists?: (command: string) => boolean;
+}
+/**
+ * Resolve the interpreter, most specific first:
+ *
+ *   1. an explicitly configured `pythonCommand`
+ *   2. `CAPTCHAKRAKEN_PYTHON`
+ *   3. the venv interpreter beside the bundled CLI
+ *   4. the first of `python3`, `python` that actually exists
+ *
+ * Falls back to `python3` rather than `python` when nothing can be probed: on
+ * the platform where the two differ, `python3` is the one that is present.
+ */
+export declare function resolvePythonCommand(options?: ResolveOptions): string;

package/dist/python-command.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Which interpreter runs the bundled CaptchaKraken CLI.
+ *
+ * This used to be `pythonCommand = 'python'`, inline in solver.ts. On
+ * Debian/Ubuntu — the most common Linux deployment target, and what CI runs —
+ * there is no `python` on PATH at all, only `python3`. So every JS solve died
+ * with `/bin/sh: 1: python: not found` before it ever reached the model, unless
+ * a `.venv` happened to exist next to the package. The type doc claimed the
+ * default was "'python' or 'python3'"; the code never tried `python3`.
+ *
+ * That is a straight violation of the rule that the Python and JS clients
+ * behave identically: the Python client obviously ran, so the divergence looked
+ * like a model or endpoint problem rather than a missing binary.
+ *
+ * Kept in its own module, with the probe injected, so the resolution order is
+ * testable without spawning anything.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PYTHON_CANDIDATES = exports.PYTHON_ENV_VAR = void 0;
+exports.resolvePythonCommand = resolvePythonCommand;
+/** Env var that overrides everything below it. */
+exports.PYTHON_ENV_VAR = 'CAPTCHA_KRAKEN_PYTHON';
+/**
+ * Candidates tried in order when nothing is configured.
+ *
+ * `python3` FIRST. On Debian-family systems `python` is absent; where both
+ * exist they are the same interpreter in practice, and PEP 394 makes `python3`
+ * the portable spelling. `python` stays as the fallback for Windows and for
+ * venvs that only expose the unsuffixed name.
+ */
+exports.PYTHON_CANDIDATES = ['python3', 'python'];
+/**
+ * Resolve the interpreter, most specific first:
+ *
+ *   1. an explicitly configured `pythonCommand`
+ *   2. `CAPTCHAKRAKEN_PYTHON`
+ *   3. the venv interpreter beside the bundled CLI
+ *   4. the first of `python3`, `python` that actually exists
+ *
+ * Falls back to `python3` rather than `python` when nothing can be probed: on
+ * the platform where the two differ, `python3` is the one that is present.
+ */
+function resolvePythonCommand(options = {}) {
+    const { configured, venvPython, env = process.env, exists } = options;
+    if (configured)
+        return configured;
+    const fromEnv = env[exports.PYTHON_ENV_VAR];
+    if (fromEnv)
+        return fromEnv;
+    if (venvPython)
+        return venvPython;
+    if (exists) {
+        for (const candidate of exports.PYTHON_CANDIDATES) {
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return exports.PYTHON_CANDIDATES[0];
+}

package/dist/slide-geometry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The algebra behind a puzzle-piece slider's closed loop.
+ *
+ * Split out of solver.ts because it is the one part of this feature that is
+ * pure arithmetic, duplicated across the two ports, and impossible to notice
+ * drifting: a wrong ratio here does not throw, it just releases the piece in the
+ * wrong place, and the puzzle fails the way an unsolved puzzle fails. Keeping it
+ * dependency-free means it can be unit-tested with `node --test` alongside
+ * limits.ts, against the same cases as
+ * `PageSolver._solve_slide_geometry` in the Python port.
+ */
+/**
+ * Piece width and handle-to-piece travel ratio, from probe measurements.
+ *
+ * Each measurement is `[handle offset, width of what changed]`, where the width
+ * spans the piece's ORIGINAL left edge to its CURRENT right edge — so
+ * `width = pieceWidth + ratio x offset`. Two of them determine both unknowns.
+ *
+ * With only one usable measurement the system is underdetermined, so `ratio` is
+ * ASSUMED to be 1 — true of every vendor observed, and the assumption is stated
+ * here rather than buried as a default. A ratio solved from implausible
+ * measurements (a redraw, a piece that hit the wall between probes) is rejected
+ * the same way: better a 1:1 guess that overshoots and gets corrected than a
+ * ratio of 0.02 that sends the handle off the track and, under camoufox, into a
+ * mouse move that never returns.
+ *
+ * `pieceWidth: null` means "could not measure" — the caller falls back to
+ * steering by the handle's own travel.
+ */
+export declare function solveSlideGeometry(widths: Array<[number, number]>, widgetWidth: number): {
+    pieceWidth: number | null;
+    ratio: number;
+};

package/dist/slide-geometry.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * The algebra behind a puzzle-piece slider's closed loop.
+ *
+ * Split out of solver.ts because it is the one part of this feature that is
+ * pure arithmetic, duplicated across the two ports, and impossible to notice
+ * drifting: a wrong ratio here does not throw, it just releases the piece in the
+ * wrong place, and the puzzle fails the way an unsolved puzzle fails. Keeping it
+ * dependency-free means it can be unit-tested with `node --test` alongside
+ * limits.ts, against the same cases as
+ * `PageSolver._solve_slide_geometry` in the Python port.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.solveSlideGeometry = solveSlideGeometry;
+/**
+ * Piece width and handle-to-piece travel ratio, from probe measurements.
+ *
+ * Each measurement is `[handle offset, width of what changed]`, where the width
+ * spans the piece's ORIGINAL left edge to its CURRENT right edge — so
+ * `width = pieceWidth + ratio x offset`. Two of them determine both unknowns.
+ *
+ * With only one usable measurement the system is underdetermined, so `ratio` is
+ * ASSUMED to be 1 — true of every vendor observed, and the assumption is stated
+ * here rather than buried as a default. A ratio solved from implausible
+ * measurements (a redraw, a piece that hit the wall between probes) is rejected
+ * the same way: better a 1:1 guess that overshoots and gets corrected than a
+ * ratio of 0.02 that sends the handle off the track and, under camoufox, into a
+ * mouse move that never returns.
+ *
+ * `pieceWidth: null` means "could not measure" — the caller falls back to
+ * steering by the handle's own travel.
+ */
+function solveSlideGeometry(widths, widgetWidth) {
+    if (!widths.length)
+        return { pieceWidth: null, ratio: 1 };
+    let ratio = 1;
+    let pieceWidth = null;
+    if (widths.length >= 2) {
+        const [o1, w1] = widths[0];
+        const [o2, w2] = widths[widths.length - 1];
+        if (o2 !== o1) {
+            const candidate = (w2 - w1) / (o2 - o1);
+            if (candidate >= MIN_RATIO && candidate <= MAX_RATIO) {
+                ratio = candidate;
+                pieceWidth = w1 - ratio * o1;
+            }
+        }
+    }
+    if (pieceWidth === null) {
+        const [o, w] = widths[widths.length - 1];
+        pieceWidth = w - ratio * o;
+    }
+    // A piece narrower than a few pixels, or wider than half the widget, is a
+    // measurement of something else — a wholesale redraw, a fade, a spinner.
+    if (pieceWidth < MIN_PIECE_PX || pieceWidth > widgetWidth * MAX_PIECE_FRACTION) {
+        return { pieceWidth: null, ratio };
+    }
+    return { pieceWidth, ratio };
+}
+// Keep these identical to the literals in page_solver.py::_solve_slide_geometry.
+const MIN_RATIO = 0.2;
+const MAX_RATIO = 3.0;
+const MIN_PIECE_PX = 3.0;
+const MAX_PIECE_FRACTION = 0.6;

package/dist/solver.d.ts

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