Subversion Repositories SmartDukaan

Rev

Rev 37450 | Blame | Compare with Previous | Last modification | View Log | RSS feed

package com.smartdukaan.cron.scheduled;

import nu.pattern.OpenCV;
import org.apache.commons.io.FileUtils;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.opencv.core.Core;
import org.opencv.core.Mat;
import org.opencv.core.Scalar;
import org.opencv.core.Size;
import org.opencv.imgcodecs.Imgcodecs;
import org.opencv.imgproc.Imgproc;
import org.json.JSONObject;
import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;
import com.smartdukaan.cron.monitored.ImeiActivationGauges;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.File;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.Instant;
import java.time.ZoneId;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;

@Component
public class CheckOppoWarrantyTask {

        @Autowired
        private ImeiActivationGauges gauges;

        private static final String BRAND = "Oppo";

    private static final Logger LOGGER = LogManager.getLogger(CheckOppoWarrantyTask.class);

    static {
        try {
            OpenCV.loadShared();
        } catch (Throwable t) {
            LogManager.getLogger(CheckOppoWarrantyTask.class).warn("OpenCV not available on this platform: {}", t.getMessage());
        }
    }

    public Map<String, LocalDate> checkWarranty(List<String> imeis) {
        Map<String, LocalDate> dateMap = new HashMap<>();
        LOGGER.info("Initiating webdriver...");

        Map<String, Object> prefsMap = new HashMap<>();
        prefsMap.put("profile.default_content_settings.popups", 0);
        prefsMap.put("download.prompt", false);
        prefsMap.put("download.directory_upgrade", true);
        System.setProperty("webdriver.chrome.driver", "/usr/bin/chromedriver");
        //I need this
        //System.setProperty("webdriver.chrome.driver", "/Users/amit/cft/chromedriver/chromedriver");
        ChromeOptions options = new ChromeOptions();
        //options.setBinary("/Users/amit/cft/chrome/Google Chrome for Testing.app/Contents/MacOS/Google Chrome For Testing");
        options.setExperimentalOption("prefs", prefsMap);
        //options.setExperimentalOption("detach", true);
        options.addArguments("--headless");
        options.addArguments("--user-agent=\"Mozilla/5.0 (Windows Phone 10.0; Android 4.2.1; Microsoft; Lumia 640 XL LTE) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Mobile Safari/537.36 Edge/12.10166\"");

        options.addArguments("--no-sandbox");
        options.addArguments("start-maximized");
        options.addArguments("disable-infobars");
        options.addArguments("--disable-extensions");
        options.addArguments("--force-device-scale-factor=1");
        options.addArguments("--test-type");
        // Headless needs no GPU, yet chrome still forks a gpu-process per browser (6 were
        // alive across the fleet). --disable-gpu removes them; --disable-dev-shm-usage
        // keeps chrome off the small /dev/shm on this box. Both are pure overhead removal,
        // no behaviour change. This box co-hosts a 9.4GB tomcat with ~3GB available and
        // has been OOM-killed twice this month, and tomcat was the victim both times.
        options.addArguments("--disable-gpu");
        options.addArguments("--disable-dev-shm-usage");
        options.addArguments("--disable-software-rasterizer");

        WebDriver driver = null;

        try {
            driver = new ChromeDriver(options);
            driver.manage().timeouts().setScriptTimeout(6, TimeUnit.SECONDS);
            driver.manage().window().setSize(new Dimension(1600, 900));
            driver.manage().window().maximize();
            // Deleting all the cookies
            driver.manage().deleteAllCookies();
            // Specifiying pageLoadTimeout and Implicit wait
            driver.manage().timeouts().pageLoadTimeout(15, TimeUnit.SECONDS);
            driver.manage().timeouts().implicitlyWait(9, TimeUnit.SECONDS);

            int mainCount = 0;
            List<String> remainingImeis = imeis;
            WebDriverWait wait10Sec = new WebDriverWait(driver, 8);
            WebDriverWait wait5Sec = new WebDriverWait(driver, 4);
            WebElement slideButton;
            Actions actionProvider = new Actions(driver);
            do {
                driver.get("https://support.oppo.com/in/warranty-check/");
                installResponseCapture(driver);
                try {
                    driver.findElement(By.cssSelector(".cp-cookie-tip a.close")).click();
                } catch (Exception e) {
                }

                for (int i = 0; i < remainingImeis.size(); i++) {
                    String imei = remainingImeis.get(i);
                    try {
                        LOGGER.info("Starting fresh with new IMEI " + imei);
                        if (driver.findElement(By.className("el-input__inner")).getAttribute("value").length() > 0) {
                            LOGGER.info("Darn.. leaving" + driver.findElement(By.className("el-input__inner")).getAttribute("value"));
                            driver.get("https://support.oppo.com/in/warranty-check/");
                            installResponseCapture(driver);
                            break;
                        }
                        driver.findElement(By.className("el-input__inner")).sendKeys(imei);

                        //driver.findElement(By.className("el-button--primary")).click();
                        driver.findElement(By.cssSelector("div.searchBtn")).click();

                        // Perform click-and-hold action on the element
                        int counter = 1;
                        boolean captchaNotBroken = true;
                        // release() is only reached on the moveByOffset > 0 path, so an attempt
                        // that fails detection or calibration leaves the button DOWN. Measured in
                        // production: 79% of presses were never released. Actions is one instance
                        // per driver, created outside the imei loop, so the stuck press leaks into
                        // the next attempt AND the next imei -- the following clickAndHold lands on
                        // an already-held button, so the widget never repositions the handle and the
                        // drag continues from wherever the pointer was abandoned.
                        boolean pressed = false;
                        do {
                            String fileName = "/tmp/oppo-simple-i-" + counter + " " + System.currentTimeMillis() + ".png";
                            try {
                                LOGGER.info("Starting Do");
                                wait10Sec.until(ExpectedConditions.visibilityOfElementLocated(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_wrapper_')]")));
                                wait10Sec.until(ExpectedConditions.visibilityOfElementLocated(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_slider_')]")));
                                By sliderBy = By.xpath("//*[starts-with(@id, 'dx_captcha_basic_slider_')]");
                                slideButton = driver.findElement(sliderBy);
                                LOGGER.info("Margin Left before- " + marginLeftOf(slideButton));
                                gauges.captchaShown(BRAND);
                                try {
                                    actionProvider.moveToElement(slideButton).clickAndHold()
                                            .moveByOffset(1, 0)
                                            .perform();
                                } catch (StaleElementReferenceException stale) {
                                    // The retry refresh (doubleClick at the end of the previous
                                    // attempt) swaps the widget's DOM, so the handle located at the
                                    // top of THIS attempt can already be detached by the time we act
                                    // on it. Re-find and try once, rather than abandoning the imei
                                    // and reloading the page: this killed 19% of oppo attempts
                                    // (54 of 284), against 0 on realme.
                                    LOGGER.info("Slider went stale before the drag - re-finding and retrying once");
                                    slideButton = driver.findElement(sliderBy);
                                    actionProvider.moveToElement(slideButton).clickAndHold()
                                            .moveByOffset(1, 0)
                                            .perform();
                                }
                                pressed = true;
                                LOGGER.info("Margin Left after - " + marginLeftOf(slideButton));
                                //Thread.sleep(5000);
                            } catch (Exception e) {
                                LOGGER.warn("Slider captcha widget (dx_captcha_basic_*) not found or not draggable"
                                        + " - reloading. Cause: " + e.getMessage());
                                driver.get("https://support.oppo.com/in/warranty-check/");
                                installResponseCapture(driver);
                                break;
                            }
                            Double ringPageX = pieceCentreX(driver);
                            double[] circles = null;
                            if (ringPageX == null) {
                                LOGGER.warn("No ring element to anchor detection on");
                            } else {
                                int bgLeft = driver.findElement(
                                        By.xpath("//*[starts-with(@id, 'dx_captcha_basic_bg_')]")).getLocation().getX();
                                circles = getMatCircles2(driver, fileName, ringPageX - bgLeft);
                            }
                            if (circles != null) {
                                double firstCircleX = circles[0];
                                double secondCircleX = circles[1];
                                double distance = Math.abs(firstCircleX - secondCircleX);
                                LOGGER.info("Distance is " + distance);

                                // Closed loop on the ring's own position; no assumed ratio.
                                int moveByOffset = aim(driver, actionProvider, circles);
                                if (moveByOffset > 0) {
                                    actionProvider.release().perform();
                                    pressed = false;
                                    LOGGER.info("Move click performed (main {}px)", moveByOffset);
                                    try {
                                        try {
                                            wait5Sec.until(ExpectedConditions.visibilityOfElementLocated(By.className("dx_captcha_basic_bar-inform")));
                                            // realme logs the widget's own verdict here and oppo did not,
                                            // which is why realme's failures name POSITION_MISMATCH and
                                            // oppo's 85% say nothing at all. Same line, oppo's variables.
                                            LOGGER.warn("Failed = {} (captcha said: {})", counter, captchaSignal(driver));
                                        } catch (Exception notFailedException) {
                                            LOGGER.info("Success  at attempt " + counter);
                                            gauges.captchaSolved(BRAND);

                                            // Read the JSON the page itself received rather than the
                                            // rendered text. The DOM value is built from two text nodes -- the
                                            // date plus a "(UTC+x)" suffix derived from the browser timezone --
                                            // and the old locator tested only the first, so it matched nothing.
                                            // The API carries regDate as epoch millis, which has no format or
                                            // timezone ambiguity at all.
                                            String json = awaitResponse(driver, 8000);
                                            LocalDate activationDate = regDateFrom(json);

                                            if (json == null) {
                                                LOGGER.warn("No getDeviceInfo response for imei {} (captcha said: {})",
                                                        imei, captchaSignal(driver));
                                            } else {
                                                LOGGER.info("Activation lookup for {} -> {}", imei,
                                                        activationDate != null ? activationDate : "no activation date");
                                            }
                                            // Always record the imei, even with a null date: findElement used to
                                            // throw here, so the row was never written and came back every run.
                                            dateMap.put(imei, activationDate);
                                            gauges.answered(BRAND, activationDate != null);
                                            clearCapture(driver);

                                            if (dateMap.size() == imeis.size()) {
                                                return dateMap;
                                            }
                                            WebElement checkAgainButton = driver.findElement(By.className("c-btn"));
                                            captchaNotBroken = false;
                                            checkAgainButton.click();
                                            break;
                                        }
                                    } catch (Throwable e) {
                                        LOGGER.warn("Failed = " + counter + " ----------" + e.getMessage());
                                    }
                                }
                            }
                            // Any path that got here without releasing (null circles, unusable
                            // calibration) must let go before the next attempt re-presses.
                            if (pressed) {
                                try {
                                    actionProvider.release().perform();
                                } catch (Exception releaseFailed) {
                                    LOGGER.warn("Could not release the slider: " + releaseFailed.getMessage());
                                }
                                pressed = false;
                            }
                            LOGGER.info("After circles conditions");
                            wait10Sec.until(ExpectedConditions.visibilityOfElementLocated(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_wrapper_')]")));
                            wait10Sec.until(ExpectedConditions.visibilityOfElementLocated(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_slider_')]")));
                            slideButton = driver.findElement(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_slider_')]"));
                            actionProvider.moveToElement(slideButton).doubleClick().perform();
                            LOGGER.info("Ending Do" + counter++);

                        } while (captchaNotBroken && counter <= MAX_CAPTCHA_ATTEMPTS);
                        // The widget-not-found path breaks out mid-iteration; do not carry a held
                        // button into the next imei.
                        if (pressed) {
                            try {
                                actionProvider.release().perform();
                            } catch (Exception releaseFailed) {
                                LOGGER.warn("Could not release the slider: " + releaseFailed.getMessage());
                            }
                        }
                        LOGGER.warn("Gave up after {} captcha attempts - imei stays pending for the next tick", MAX_CAPTCHA_ATTEMPTS);
                    } catch (Exception e) {
                        LOGGER.error("Oppo warranty check failed for imei " + imei, e);
                    }
                    driver.get("https://support.oppo.com/in/warranty-check/");
                    // Every navigation destroys the JS context, taking the capture hook
                    // with it. Miss one of these and the page is blind from the second
                    // imei onwards: __oppoResp and __oppoCaptcha both come back null,
                    // which reads as "the captcha failed" when it may well have passed.
                    installResponseCapture(driver);
                }
                mainCount++;
                remainingImeis = imeis.stream().filter(x -> !dateMap.containsKey(x)).collect(Collectors.toList());
                if (remainingImeis.isEmpty()) break;
            } while (mainCount < 5);
        } finally {
            if (driver != null) {
                try {
                    driver.quit(); //Ensures cleanup even on return or error
                } catch (Exception e) {
                    LOGGER.warn("Error closing driver: " + e.getMessage());
                }
            }
        }

        return dateMap;
    }


    /** Stash the getDeviceInfo response on window as the page receives it. */
    private void installResponseCapture(WebDriver driver) {
        try {
            ((JavascriptExecutor) driver).executeScript(
                "if (!window.__oppoCapInstalled) {"
              + "  window.__oppoCapInstalled = true; window.__oppoResp = null; window.__oppoCaptcha = null;"
              // __oppoCaptcha is last-captcha-call-wins, and the widget refetches a puzzle
              // (/api/a) straight after a rejected verify (/api/v1). We then wait up to 5s
              // for the error element before reading it, which is ample time for the
              // refetch to overwrite the verdict -- so "all failures show /api/a" cannot
              // distinguish "never verified" from "verified, rejected, then overwritten".
              // Keep the verify separately, and a count, so the two are distinguishable.
              + "  window.__oppoVerify = null; window.__oppoVerifyCount = 0;"
              // axios can sit on either transport, and realme's page uses fetch --
              // an XHR-only hook silently captures nothing, which is exactly what
              // 'no getDeviceInfo response captured' was reporting.
              + "  var O = XMLHttpRequest.prototype.open;"
              + "  XMLHttpRequest.prototype.open = function(m,u){"
              + "    this.addEventListener('load', function(){"
              + "      try { var s=String(u);"
              + "        if (s.indexOf('getDeviceInfo') !== -1) window.__oppoResp = this.responseText;"
              + "        else if (s.indexOf('/api/v1') !== -1) { window.__oppoVerifyCount++; window.__oppoVerify = (this.responseText||'').slice(0,160); window.__oppoCaptcha = s + ' -> ' + (this.responseText||'').slice(0,200); }"
              + "        else if (s.indexOf('captcha') !== -1) window.__oppoCaptcha = s + ' -> ' + (this.responseText||'').slice(0,200);"
              + "      } catch(e){}"
              + "    });"
              + "    return O.apply(this, arguments);"
              + "  };"
              + "  var F = window.fetch;"
              + "  if (F) { window.fetch = function(){"
              + "    var u = arguments[0]; u = (u && u.url) ? u.url : String(u);"
              + "    return F.apply(this, arguments).then(function(r){"
              + "      try { if (u.indexOf('getDeviceInfo') !== -1) { r.clone().text().then(function(t){ window.__oppoResp = t; }); } } catch(e){}"
              + "      return r;"
              + "    });"
              + "  }; }"
              // A window.fetch wrapper only catches clients that resolve fetch at call
              // time. Anything that captured globalThis.fetch when its bundle loaded --
              // Nuxt's $fetch/ofetch does exactly this, and it is what hid realme's
              // lookup from us -- sails straight past it. Response.prototype is resolved
              // per call, so it catches every client regardless.
              // Read the clone with the ORIGINAL reader; the patched one recurses forever.
              + "  ['json','text'].forEach(function(name){"
              + "    var orig = Response.prototype[name];"
              + "    if (!orig) return;"
              + "    Response.prototype[name] = function(){"
              + "      try { var u = this.url || '';"
              + "        if (u.indexOf('getDeviceInfo') !== -1 && !this.__oppoSeenBody) {"
              + "          var c = this.clone(); c.__oppoSeenBody = 1;"
              + "          orig.call(c).then(function(t){ window.__oppoResp = (typeof t === 'string') ? t : JSON.stringify(t); });"
              + "        } } catch(e){}"
              + "      return orig.apply(this, arguments);"
              + "    };"
              + "  });"
              + "}");
        } catch (Exception e) {
            LOGGER.warn("Could not install the response capture hook: " + e.getMessage());
        }
    }

    /** Last response from the captcha widget itself -- says WHY a drag was refused. */
    private String captchaSignal(WebDriver driver) {
        try {
            Object v = ((JavascriptExecutor) driver).executeScript(
                    "return 'verifies=' + (window.__oppoVerifyCount||0)"
                  + " + ' lastVerify=' + (window.__oppoVerify || 'NONE')"
                  + " + ' | ' + (window.__oppoCaptcha || 'none');");
            return v == null ? null : v.toString();
        } catch (Exception e) {
            return null;
        }
    }

    /** Poll for the response instead of reading once: the success signal can fire
     *  before the lookup request has completed, which loses the payload. */
    private String awaitResponse(WebDriver driver, long timeoutMs) {
        long deadline = System.currentTimeMillis() + timeoutMs;
        while (System.currentTimeMillis() < deadline) {
            String json = capturedResponse(driver);
            if (json != null && !json.trim().isEmpty()) return json;
            try {
                Thread.sleep(300);
            } catch (InterruptedException ie) {
                Thread.currentThread().interrupt();
                return null;
            }
        }
        return null;
    }

    private String capturedResponse(WebDriver driver) {
        try {
            Object v = ((JavascriptExecutor) driver).executeScript("return window.__oppoResp || null;");
            return v == null ? null : v.toString();
        } catch (Exception e) {
            return null;
        }
    }

    private void clearCapture(WebDriver driver) {
        try {
            ((JavascriptExecutor) driver).executeScript("window.__oppoResp = null;");
        } catch (Exception ignored) {
        }
    }

    /** data.regDate is epoch millis; absent or blank means the device is not activated yet. */
    private LocalDate regDateFrom(String json) {
        if (json == null) return null;
        try {
            JSONObject data = new JSONObject(json).optJSONObject("data");
            if (data == null) return null;
            String reg = data.optString("regDate", "");
            if (reg == null || reg.trim().isEmpty() || "null".equals(reg)) return null;
            return Instant.ofEpochMilli(Long.parseLong(reg.trim()))
                    .atZone(ZoneId.of("Asia/Kolkata")).toLocalDate();
        } catch (Exception e) {
            LOGGER.warn("Could not read regDate from the Oppo response: " + e.getMessage());
            return null;
        }
    }

    /**
     * How close the ring must get to the hole before we release, in px.
     *
     * There is deliberately NO assumed ratio anywhere in this class. px-per-px is derived
     * from real movement on every attempt and re-derived on every step within it -- see
     * aim(). Earlier revisions carried an ASSUMED_RATIO constant, it was tuned twice
     * (1.7 -> 0.67 -> 1.7) against contaminated measurements, and it never helped. Do not
     * reintroduce one: the widget's px-per-px genuinely varies by environment (1.4-1.5 in
     * production, 1.1-1.2 locally) and by brand, which is exactly why it must be measured.
     */
    /**
     * Captcha attempts per imei per tick, before giving up and letting the next tick
     * retry with a FRESH page and session.
     *
     * A captcha failure is a technical failure, not an answer, so the imei is never
     * abandoned -- it stays pending and comes back in ~5 minutes. What this caps is how
     * many times we grind on it inside one already-refused session.
     *
     * 20 was right before the drag was fixed: pre-glide, 33% of oppo's successes came
     * from attempts 8-20. Post-glide (r37440) the drag lands first or second try and the
     * tail stopped paying. Measured over 308 post-glide successes and 279 exhausted imeis:
     *   cap  5 -> 95.5% of successes kept, 67.7% of captcha work saved
     *   cap  7 -> 97.7% kept, 58.4% saved   <- here
     *   cap 10 -> 99.0% kept, 44.8% saved
     * Realme keeps its own, higher cap: it has no glide yet, so its successes still
     * spread to attempt 10+ and 7 would cost it 16.5%. Re-check the histogram after a
     * day; if the distribution shifts, so should this.
     */
    private static final int MAX_CAPTCHA_ATTEMPTS = 7;

    private static final double ALIGNED_PX = 2.0;

    /**
     * margin-left for logging only. Reading it off a detached element throws, and this is
     * a diagnostic -- it must never be the reason an attempt is abandoned.
     */
    private String marginLeftOf(WebElement el) {
        try {
            return el.getCssValue("margin-left");
        } catch (Exception e) {
            return "?";
        }
    }

    /** Seed probe, in slider px. Deliberately small: it only has to produce a first
     *  measurable movement, and it must be too small to cross the hole. */
    private static final int SEED_NUDGE = 12;
    /** Sub-moves per leg, and the pause between them. A leg is traversed as many small
     *  eased steps rather than one jump, so the pointer describes a continuous path. */
    private static final int MAX_GLIDE_STEPS = 18;
    private static final int GLIDE_PX_PER_STEP = 8;
    private static final long GLIDE_PAUSE_MS = 45;
    private static final int MAX_AIM_STEPS = 5;
    private static final int MAX_STEP = 140;

    /**
     * Traverse one leg as many small eased sub-moves instead of a single jump.
     *
     * Nothing about the distance changes -- it is still whatever the derived ratio says.
     * Only the path does. The widget scores trajectory as well as final position, and
     * returns POSITION_MISMATCH for either, so a drag that teleports in 2 jumps and one
     * that slides in over 15 are not equally credible. Realme holds ~1.93s and converts
     * 54-74%; oppo held 0.91s in 2-3 jumps and converts 15%. That is suggestive, not
     * proof -- this change is the test.
     *
     * Ease-out (1-(1-t)^2) so it starts quickly and settles, which is how a hand moves.
     */
    private void glide(Actions actionProvider, int distance) throws InterruptedException {
        int steps = Math.abs(distance) / GLIDE_PX_PER_STEP;
        if (steps > MAX_GLIDE_STEPS) steps = MAX_GLIDE_STEPS;
        if (steps <= 1) {
            actionProvider.moveByOffset(distance, 0).perform();
            return;
        }
        int done = 0;
        for (int i = 1; i <= steps; i++) {
            double t = (double) i / steps;
            int cumulative = (int) Math.round(distance * (1 - Math.pow(1 - t, 2)));
            int delta = cumulative - done;
            if (delta != 0) {
                actionProvider.moveByOffset(delta, 0).perform();
                done += delta;
            }
            Thread.sleep(GLIDE_PAUSE_MS);
        }
        if (done != distance) {
            actionProvider.moveByOffset(distance - done, 0).perform();
        }
    }

    /** Centre of the draggable ring, in page CSS px, or null if it is not there. */
    private Double pieceCentreX(WebDriver driver) {
        try {
            WebElement piece = driver.findElement(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_sub-slider_')]"));
            return piece.getLocation().getX() + (piece.getSize().getWidth() / 2.0);
        } catch (Exception e) {
            return null;
        }
    }

    /**
     * Drag the ring onto the hole, deriving px-per-px as we go.
     *
     * Why this does not re-run circle detection: it cannot. Hough needs to resolve TWO
     * circles of similar radius, and as the ring closes on the hole they overlap and stop
     * being two -- so the measurement dies exactly at convergence. Measured in production
     * after r37437: 25 of 36 attempts lost the circles on the very step after the main
     * move, and NOT ONE ever reported aligned. The old refine() hit the same wall and
     * silently released. Any loop built on "distance between two detected circles" is
     * blind at the only moment that matters.
     *
     * So the target is fixed ONCE, from the detection already done while the two are far
     * apart and resolvable, and from then on we track the RING'S OWN ELEMENT, which stays
     * readable however close it gets. Verified locally against the live widget: the ring's
     * rect tracks the drag cleanly the whole way in (+10 mouse -> +11 ring, repeatably).
     *
     * The circle x's are already CSS px relative to the bg element -- the crop in
     * getMatCircles2 uses CSS coordinates and chrome runs with
     * --force-device-scale-factor=1 -- so the only conversion needed is the bg offset.
     *
     * Every move is also a measurement: the ratio is re-derived from what that move
     * actually achieved, and it is signed, so overshoot corrects itself instead of needing
     * to be detected.
     *
     * @return total slider px moved, or 0 if the ring could not be located at all.
     */
    private int aim(WebDriver driver, Actions actionProvider, double[] circleXs) throws Exception {
        Double piece = pieceCentreX(driver);
        if (piece == null) {
            LOGGER.warn("Aim: no ring element to track");
            return 0;
        }
        int bgX;
        try {
            bgX = driver.findElement(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_bg_')]")).getLocation().getX();
        } catch (Exception e) {
            LOGGER.warn("Aim: bg element gone - " + e.getMessage());
            return 0;
        }

        // Of the two detected circles the ring is whichever sits at the ring element; the
        // other one is the hole we are aiming at.
        double a = bgX + circleXs[0], b = bgX + circleXs[1];
        double target = (Math.abs(a - piece) <= Math.abs(b - piece)) ? b : a;
        LOGGER.info("Aim: ring at {} target at {} ({}px to close)",
                Math.round(piece), Math.round(target), Math.round(target - piece));

        double ratio = 0;               // ring px per mouse px, signed, derived from real moves
        int total = 0;
        int step = SEED_NUDGE;

        for (int i = 0; i < MAX_AIM_STEPS; i++) {
            glide(actionProvider, step);
            total += step;

            Double now = pieceCentreX(driver);
            if (now == null) {
                LOGGER.warn("Aim step {}: lost the ring after {}px", i, total);
                return total;
            }
            double moved = now - piece;
            if (Math.abs(moved) > 0.5) {
                double observed = moved / step;
                ratio = (ratio == 0) ? observed : (ratio + observed) / 2;
            }
            double remaining = target - now;
            LOGGER.info("Aim step {}: mouse {}px -> ring moved {}px, {}px left, ratio {}",
                    i, step, Math.round(moved), Math.round(remaining), String.format("%.2f", ratio));

            if (Math.abs(remaining) <= ALIGNED_PX) {
                LOGGER.info("Aim: aligned to {}px after {} step(s), {}px of slider",
                        Math.round(remaining), i + 1, total);
                return total;
            }
            piece = now;
            if (ratio == 0) {           // nothing measurable yet, probe again
                step = SEED_NUDGE;
                continue;
            }
            int next = (int) Math.round(remaining / ratio);
            if (next == 0) next = (remaining > 0 ? 1 : -1);
            if (next > MAX_STEP) next = MAX_STEP;
            if (next < -MAX_STEP) next = -MAX_STEP;
            step = next;
        }
        LOGGER.info("Aim: {} steps used, {}px of slider, still short", MAX_AIM_STEPS, total);
        return total;
    }

    private Mat getMatCircles(WebDriver driver, String fileName) throws Exception {

        File screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE);
        BufferedImage fullImg = ImageIO.read(screenshot);

        // Get the location of element on the page
        WebElement imageElement = driver.findElement(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_bg_')]"));
        Point point = imageElement.getLocation();

        // Get width and height of the element
        int eleWidth = imageElement.getSize().getWidth();
        int eleHeight = imageElement.getSize().getHeight();

        // Crop the entire page screenshot to get only element screenshot
        BufferedImage eleScreenshot = fullImg.getSubimage(point.getX(), point.getY(),
                eleWidth, eleHeight);
        ImageIO.write(eleScreenshot, "png", screenshot);

        // Copy the element screenshot to disk
        File screenshotLocation = new File(fileName);
        FileUtils.copyFile(screenshot, screenshotLocation);

        Imgcodecs imageCodecs = new Imgcodecs();
        Mat grayMatrix = imageCodecs.imread(fileName, Imgcodecs.IMREAD_COLOR);
        Imgproc.cvtColor(grayMatrix, grayMatrix, Imgproc.COLOR_BGR2GRAY);
        Mat medianBlur = new Mat();
        Imgproc.medianBlur(grayMatrix, medianBlur, 5);
        Mat circles = new Mat();
        Imgproc.HoughCircles(medianBlur, circles, Imgproc.HOUGH_GRADIENT, 1, 15, 50, 20, 17, 25);
        return circles;
    }

    /** Anything within this many px of the ring's known centre IS the ring, not the hole. */
    private static final double RING_EXCLUSION_PX = 30;
    /** A real hole sits at least this far below the frame's mean luminance. */
    private static final double MIN_HOLE_DARKNESS = 15;

    /** Mean luminance inside a detected circle, clamped to the image. */
    private double meanInside(Mat gray, double[] circle) {
        int r = (int) Math.max(3, circle[2] * 0.6);            // inner core, avoids the rim
        int x0 = (int) Math.max(0, circle[0] - r), y0 = (int) Math.max(0, circle[1] - r);
        int x1 = (int) Math.min(gray.cols(), circle[0] + r), y1 = (int) Math.min(gray.rows(), circle[1] + r);
        if (x1 - x0 < 2 || y1 - y0 < 2) return Double.MAX_VALUE;
        return Core.mean(gray.submat(y0, y1, x0, x1)).val[0];
    }

    /**
     * Locate the hole. The RING is not detected -- its exact position comes from the DOM
     * (dx_captcha_basic_sub-slider_), so hough only has to find one thing instead of two.
     *
     * The old version demanded TWO circles whose radii matched within 3px and returned
     * null otherwise, so a puzzle where the hole was found perfectly well still failed if
     * the ring was missed or the radii differed by 4px. It was also re-detecting something
     * already known exactly.
     *
     * param1 is the Canny HIGH threshold: edges weaker than it are discarded before circle
     * finding begins. At 100 a low-contrast hole produces no edge at all. Measured on four
     * live puzzles, hole-vs-background contrast was 98, 103, 28 and 117 -- the 28 (a pale
     * lilac background) cannot survive 100, which is the mechanism behind "60% of attempts
     * never find the circles". Dropped to 50.
     *
     * @param ringRelX ring centre in px relative to the bg element's left edge
     * @return {ringRelX, holeRelX} -- shape kept so callers are unchanged -- or null
     */
    private double[] getMatCircles2(WebDriver driver, String fileName, double ringRelX) throws Exception {
        File screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE);
        BufferedImage fullImg = ImageIO.read(screenshot);

        // Get the location of element on the page
        WebElement imageElement = driver.findElement(By.xpath("//*[starts-with(@id, 'dx_captcha_basic_bg_')]"));
        Point point = imageElement.getLocation();

        // Get width and height of the element
        int eleWidth = imageElement.getSize().getWidth();
        int eleHeight = imageElement.getSize().getHeight();

        // Crop the entire page screenshot to get only element screenshot
        BufferedImage eleScreenshot = fullImg.getSubimage(point.getX(), point.getY(),
                eleWidth, eleHeight);
        ImageIO.write(eleScreenshot, "png", screenshot);

        // Copy the element screenshot to disk
        File screenshotLocation = new File(fileName);
        FileUtils.copyFile(screenshot, screenshotLocation);

        Mat src = Imgcodecs.imread(fileName);
        if (src.empty()) {
            System.err.println("Cannot read image: " + fileName);
            new File(fileName).delete();
            return null;
        }

        Mat gray = new Mat();
        Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
        Imgproc.GaussianBlur(gray, gray, new Size(9, 9), 2, 2);

        Mat circles = new Mat();
        Imgproc.HoughCircles(gray, circles, Imgproc.HOUGH_GRADIENT, 1.0,
                20, // min distance between centers
                50, 20, // param1 (Canny high threshold), param2 (accumulator threshold)
                10, 50); // minRadius, maxRadius

        if (circles.cols() < 1) {
            new File(fileName).delete();
            return null;
        }

        // Dropping param1 to 50 lets weak edges through, which also lets textured
        // backgrounds (the sand images especially) produce spurious circles. Without the
        // old two-circle pairing there is nothing else to reject them, so verify the
        // candidate is actually a HOLE: it must be materially darker than the picture as
        // a whole. Measured on live puzzles the hole runs 28-117 luminance below the
        // median, so 15 rejects noise while keeping even the faintest real hole.
        Scalar frameMean = Core.mean(gray);
        // OpenCV returns circles strongest-accumulator first, so take the first candidate
        // that is not the ring and does look like a hole.
        for (int i = 0; i < circles.cols(); i++) {
            double[] c = circles.get(0, i);
            if (Math.abs(c[0] - ringRelX) < RING_EXCLUSION_PX) continue; // that is the ring
            double darkness = frameMean.val[0] - meanInside(gray, c);
            if (darkness < MIN_HOLE_DARKNESS) {
                LOGGER.info("Rejecting circle at {}px: only {} darker than the frame",
                        Math.round(c[0]), Math.round(darkness));
                continue;
            }
            new File(fileName).delete();
            return new double[] { ringRelX, c[0] };
        }

        LOGGER.info("Detected {} circle(s) but all sat on the ring at {}px", circles.cols(), Math.round(ringRelX));
        new File(fileName).delete();
        return null;
    }


}