captchaforge 0.2.39

//! Trusted, cross-origin-correct image-grid clicking.
//!
//! reCAPTCHA v2's image grid and hCaptcha render their tile table inside a
//! **cross-origin** out-of-process iframe (`google.com/recaptcha/api2/bframe`,
//! `*.hcaptcha.com`). The legacy click path in the YOLO and VLM solvers ran
//!
//! ```js
//! el.dispatchEvent(new MouseEvent('click', …))
//! ```
//!
//! in the **main** document. That fails twice over:
//!
//! 1. `document.querySelectorAll('.rc-imageselect-tile')` in the parent page
//!    returns nothing, the tiles live in the cross-origin frame, invisible to
//!    parent JS (so it could never even find the tiles on a real challenge).
//! 2. A synthetic `MouseEvent` carries `isTrusted === false`, the single
//!    property every modern anti-bot checkbox/tile gates on. Even where the
//!    element was reachable (local same-origin fixtures), the click was a
//!    giveaway.
//!
//! This module fixes both with one path shared by both vision solvers:
//!
//! - [`crate::frame::find_tiles_in_frames`] walks the frame tree (BiDi
//!   per-context evaluation pierces cross-origin frames) and returns every
//!   tile's bounding box in **main-viewport** coordinates.
//! - Each selected tile is clicked with [`behavior::click_realistic`] → BiDi
//!   `input.performActions`, so the delivered pointer event is `isTrusted`
//!   and routes into the owning (possibly cross-origin) frame, exactly the
//!   path proven by foxdriver's `cross_origin_click` integration test.
//!
//! The tile/verify selector lists were previously duplicated inline in both
//! `yolo_grid.rs` and `vlm.rs` (and had already drifted apart). They live here
//! now as the single source of truth.

use crate::behavior;
use crate::frame::FrameTile;
use crate::Page;
use tracing::warn;

/// Tile-container selectors, in priority order. The first selector that matches
/// in any frame wins. Centralized so the YOLO and VLM grid solvers share one
/// list (they previously carried two divergent inline copies).
pub(crate) const GRID_TILE_PROBES: &[&str] = &[
    // reCAPTCHA v2 image grid (tiles live in the api2/bframe OOPIF).
    ".rc-imageselect-tile",
    // hCaptcha challenge grid.
    ".task-image",
    ".image-task",
    ".hcaptcha-checkbox-img",
    // Table-cell fallbacks for both providers.
    ".rc-imageselect-table td",
    ".hcaptcha-table td",
    ".captcha-grid > .tile",
    // Generic local-mock fixtures (icon / color / image pickers).
    "#widget .icon-item",
    "#widget .color-item",
    "#widget .cell",
    "#widget .grid > .cell",
];

/// Verify / submit button selectors, in priority order.
pub(crate) const GRID_VERIFY_PROBES: &[&str] = &[
    "#recaptcha-verify-button",
    ".rc-button-default",
    ".button-submit",
    "[data-pp=\"submit\"]",
    "button[type=\"submit\"]",
    "#widget #submit",
    "#widget button",
];

/// Locate the challenge tiles across the whole frame tree, trying each probe
/// selector in priority order. Returns the matched tiles (viewport-relative)
/// and the selector that matched, or `None` if nothing matches anywhere.
///
/// Mirrors the legacy inline "first non-empty `querySelectorAll` wins" logic,
/// but across every frame instead of only the main document.
pub(crate) async fn locate_grid_tiles(page: &Page) -> Option<(Vec<FrameTile>, &'static str)> {
    for sel in GRID_TILE_PROBES {
        if let Ok(tiles) = crate::frame::find_tiles_in_frames(page, sel).await {
            if !tiles.is_empty() {
                return Some((tiles, sel));
            }
        }
    }
    None
}

/// Click the tiles at `indices` with TRUSTED, cross-origin-correct input, then
/// click the verify/submit button. Returns the number of tiles actually
/// clicked.
///
/// `indices` are 0-based positions within the tile grid in document order
/// (the same indexing the YOLO/VLM mapping produces). Indices that don't
/// resolve to a located tile are skipped.
pub(crate) async fn click_grid_tiles_trusted(page: &Page, indices: &[usize]) -> usize {
    let Some((tiles, _sel)) = locate_grid_tiles(page).await else {
        return 0;
    };
    click_located_tiles(page, &tiles, indices).await
}

/// Click an already-located tile set at `indices`. Split out from
/// [`click_grid_tiles_trusted`] so the YOLO path, which locates the tiles once
/// to derive grid geometry, can reuse the same tile list without a second
/// frame walk.
pub(crate) async fn click_located_tiles(
    page: &Page,
    tiles: &[FrameTile],
    indices: &[usize],
) -> usize {
    // O(1) lookup by the tile's in-frame document index.
    let by_index: std::collections::HashMap<usize, FrameTile> =
        tiles.iter().map(|t| (t.index, *t)).collect();

    let mut clicked = 0usize;
    let mut last: Option<(f64, f64)> = None;
    for &idx in indices {
        let Some(tile) = by_index.get(&idx) else {
            continue;
        };
        let (cx, cy) = tile.centre();
        // Human trajectory from the previous tile into this one, then a
        // trusted click. The move makes the pointer path realistic; the
        // click_realistic call dispatches a real BiDi pointer event
        // (isTrusted === true) that routes into the owning frame.
        if let Some((px, py)) = last {
            // Law 10: surface a failed inter-tile move instead of `let _ =`. A
            // missing trajectory makes the trusted click that follows land "cold"
            // (no realistic pointer path), a weaker but still-attempted click.
            if let Err(e) = behavior::mouse_move_human(page, px, py, cx, cy).await {
                warn!("grid-click inter-tile move failed ({e}); clicking tile without a realistic approach path");
            }
        }
        if behavior::click_realistic(page, cx, cy).await.is_ok() {
            clicked += 1;
        }
        last = Some((cx, cy));
        // Pace between tile selections like a human scanning the grid.
        behavior::random_pause(120, 360).await;
    }

    // Law 10: the verify/submit click is what actually submits the grid selection.
    // `click_verify_button` returns `false` when no submit control was found/clicked
    //: the prior `let _ =` discarded that, so the selection silently went
    // unsubmitted while the caller saw a non-zero `clicked` and assumed progress.
    if clicked > 0 && !click_verify_button(page).await {
        warn!(
            "grid-click selected {clicked} tile(s) but no verify/submit button was found to click; \
             the selection was NOT submitted, the solve will not advance from this grid"
        );
    }
    clicked
}

/// Click the first matching verify/submit button found anywhere in the frame
/// tree, with a trusted click. Returns `true` if a button was clicked.
pub(crate) async fn click_verify_button(page: &Page) -> bool {
    for sel in GRID_VERIFY_PROBES {
        if let Ok(Some((x, y))) = crate::frame::find_element_centre_in_frames(page, sel).await {
            if behavior::click_realistic(page, x, y).await.is_ok() {
                return true;
            }
        }
    }
    false
}

/// The union bounding box `(left, top, width, height)` of a set of tiles, in
/// the same coordinate space as the tiles. Returns `None` for an empty slice.
///
/// Used to crop a full-page screenshot down to just the grid before running
/// object detection: without this, detection coordinates are normalized over
/// the *whole viewport* but then mapped as if the screenshot *were* the grid,
/// which is only true for a full-bleed local fixture, never for a real
/// floating reCAPTCHA challenge popup.
///
/// Only the local-inference (`vision`) crop path consumes this; the VLM path
/// sends the full screenshot to the model and clicks by tile index.
#[cfg(feature = "vision")]
pub(crate) fn grid_region(tiles: &[FrameTile]) -> Option<(f64, f64, f64, f64)> {
    let first = tiles.first()?;
    let mut l = first.left;
    let mut t = first.top;
    let mut r = first.left + first.width;
    let mut b = first.top + first.height;
    for tile in &tiles[1..] {
        l = l.min(tile.left);
        t = t.min(tile.top);
        r = r.max(tile.left + tile.width);
        b = b.max(tile.top + tile.height);
    }
    Some((l, t, (r - l).max(0.0), (b - t).max(0.0)))
}

/// Count distinct clusters in a sorted-on-the-fly set of 1-D coordinates,
/// treating values within `tol` of each other as the same cluster. Pulled out
/// as a pure helper so [`infer_grid_dims`] is unit-testable without a browser.
#[cfg(feature = "vision")]
fn count_clusters(vals: impl Iterator<Item = f64>, tol: f64) -> usize {
    let mut xs: Vec<f64> = vals.collect();
    xs.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
    if xs.is_empty() {
        return 0;
    }
    let mut clusters = 1usize;
    for w in xs.windows(2) {
        if (w[1] - w[0]).abs() > tol {
            clusters += 1;
        }
    }
    clusters
}

/// Infer the `(cols, rows)` of a tile grid from tile geometry by clustering
/// distinct column (x-centre) and row (y-centre) positions. The clustering
/// tolerance is derived from the tiles' own minimum dimension (half a tile),
/// so it adapts to the challenge's actual pitch rather than a magic constant.
///
/// More robust than `round(sqrt(n))`: it handles 3×3, 4×4, and ragged/partial
/// grids (a last row with fewer tiles) correctly.
///
/// Only the local-inference (`vision`) path consumes this.
#[cfg(feature = "vision")]
pub(crate) fn infer_grid_dims(tiles: &[FrameTile]) -> Option<(usize, usize)> {
    if tiles.is_empty() {
        return None;
    }
    let min_w = tiles.iter().map(|t| t.width).fold(f64::INFINITY, f64::min);
    let min_h = tiles.iter().map(|t| t.height).fold(f64::INFINITY, f64::min);
    let col_tol = (min_w / 2.0).max(1.0);
    let row_tol = (min_h / 2.0).max(1.0);
    let cols = count_clusters(tiles.iter().map(|t| t.left + t.width / 2.0), col_tol);
    let rows = count_clusters(tiles.iter().map(|t| t.top + t.height / 2.0), row_tol);
    if cols == 0 || rows == 0 {
        return None;
    }
    Some((cols, rows))
}

/// Map a CSS-pixel rect in viewport space to a device-pixel crop box of a
/// screenshot whose dimensions are `img_w`×`img_h`, given the CSS viewport size
/// `css_vw`×`css_vh`.
///
/// Firefox's BiDi screenshot is captured at the device pixel ratio, so a CSS
/// rect must be scaled by `img_w/css_vw` (x) and `img_h/css_vh` (y). The result
/// is clamped to the image bounds. Returns `None` if any input dimension is
/// non-positive or the resulting crop is empty.
///
/// Only the local-inference (`vision`) crop path consumes this.
#[cfg(feature = "vision")]
pub(crate) fn scale_rect_to_image(
    rect: (f64, f64, f64, f64),
    css_vw: f64,
    css_vh: f64,
    img_w: u32,
    img_h: u32,
) -> Option<(u32, u32, u32, u32)> {
    if css_vw <= 0.0 || css_vh <= 0.0 || img_w == 0 || img_h == 0 {
        return None;
    }
    let sx = img_w as f64 / css_vw;
    let sy = img_h as f64 / css_vh;
    let (l, t, w, h) = rect;
    let x0 = (l * sx).clamp(0.0, img_w as f64);
    let y0 = (t * sy).clamp(0.0, img_h as f64);
    let x1 = ((l + w) * sx).clamp(0.0, img_w as f64);
    let y1 = ((t + h) * sy).clamp(0.0, img_h as f64);
    let cw = (x1 - x0).max(0.0) as u32;
    let ch = (y1 - y0).max(0.0) as u32;
    if cw == 0 || ch == 0 {
        return None;
    }
    Some((x0 as u32, y0 as u32, cw, ch))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn probe_lists_are_nonempty_and_cover_both_providers() {
        assert!(
            GRID_TILE_PROBES.contains(&".rc-imageselect-tile"),
            "reCAPTCHA tiles"
        );
        assert!(GRID_TILE_PROBES.contains(&".task-image"), "hCaptcha tiles");
        assert!(!GRID_VERIFY_PROBES.is_empty());
        assert!(GRID_VERIFY_PROBES.contains(&"#recaptcha-verify-button"));
    }

    #[test]
    fn probe_lists_have_no_duplicates() {
        for (i, a) in GRID_TILE_PROBES.iter().enumerate() {
            for b in &GRID_TILE_PROBES[i + 1..] {
                assert_ne!(a, b, "duplicate tile probe {a}");
            }
        }
        for (i, a) in GRID_VERIFY_PROBES.iter().enumerate() {
            for b in &GRID_VERIFY_PROBES[i + 1..] {
                assert_ne!(a, b, "duplicate verify probe {a}");
            }
        }
    }
}

/// Geometry helpers are consumed only by the local-inference (`vision`) crop
/// path, so their pure-math truth tests live in the `vision` lane alongside
/// them.
#[cfg(all(test, feature = "vision"))]
mod geom_tests {
    use super::*;

    fn tile(index: usize, left: f64, top: f64, w: f64, h: f64) -> FrameTile {
        FrameTile {
            index,
            left,
            top,
            width: w,
            height: h,
        }
    }

    #[test]
    fn grid_region_unions_all_tiles() {
        let tiles = vec![
            tile(0, 10.0, 10.0, 50.0, 50.0),
            tile(1, 70.0, 10.0, 50.0, 50.0),
            tile(2, 10.0, 70.0, 50.0, 50.0),
        ];
        // left=10, top=10, right=120, bottom=120 → w=110, h=110.
        assert_eq!(grid_region(&tiles), Some((10.0, 10.0, 110.0, 110.0)));
    }

    #[test]
    fn grid_region_empty_is_none() {
        assert_eq!(grid_region(&[]), None);
    }

    #[test]
    fn infer_grid_dims_3x3() {
        // 3 columns × 3 rows of 100px tiles.
        let mut tiles = Vec::new();
        let mut idx = 0;
        for row in 0..3 {
            for col in 0..3 {
                tiles.push(tile(
                    idx,
                    col as f64 * 100.0,
                    row as f64 * 100.0,
                    100.0,
                    100.0,
                ));
                idx += 1;
            }
        }
        assert_eq!(infer_grid_dims(&tiles), Some((3, 3)));
    }

    #[test]
    fn infer_grid_dims_4x4() {
        let mut tiles = Vec::new();
        let mut idx = 0;
        for row in 0..4 {
            for col in 0..4 {
                tiles.push(tile(idx, col as f64 * 80.0, row as f64 * 80.0, 80.0, 80.0));
                idx += 1;
            }
        }
        assert_eq!(infer_grid_dims(&tiles), Some((4, 4)));
    }

    #[test]
    fn infer_grid_dims_tolerates_subpixel_jitter() {
        // Same 3-column layout but with sub-pixel rounding noise; centres
        // within half a tile must still cluster to 3 columns.
        let tiles = vec![
            tile(0, 0.3, 0.0, 100.0, 100.0),
            tile(1, 100.1, 0.4, 100.0, 100.0),
            tile(2, 199.7, 0.0, 100.0, 100.0),
        ];
        assert_eq!(infer_grid_dims(&tiles), Some((3, 1)));
    }

    #[test]
    fn infer_grid_dims_ragged_last_row() {
        // 3 columns, last row only has 1 tile → still 3 cols, 2 rows.
        let tiles = vec![
            tile(0, 0.0, 0.0, 100.0, 100.0),
            tile(1, 100.0, 0.0, 100.0, 100.0),
            tile(2, 200.0, 0.0, 100.0, 100.0),
            tile(3, 0.0, 100.0, 100.0, 100.0),
        ];
        assert_eq!(infer_grid_dims(&tiles), Some((3, 2)));
    }

    #[test]
    fn infer_grid_dims_empty_is_none() {
        assert_eq!(infer_grid_dims(&[]), None);
    }

    #[test]
    fn scale_rect_dpr1_identity() {
        // viewport 1000x800, screenshot 1000x800 (DPR 1) → identity.
        let r = scale_rect_to_image((100.0, 50.0, 200.0, 150.0), 1000.0, 800.0, 1000, 800);
        assert_eq!(r, Some((100, 50, 200, 150)));
    }

    #[test]
    fn scale_rect_dpr2_doubles() {
        // viewport 1000x800, screenshot 2000x1600 (DPR 2) → coords double.
        let r = scale_rect_to_image((100.0, 50.0, 200.0, 150.0), 1000.0, 800.0, 2000, 1600);
        assert_eq!(r, Some((200, 100, 400, 300)));
    }

    #[test]
    fn scale_rect_clamps_to_image_bounds() {
        // Rect overflowing the viewport is clamped to the image edge.
        let r = scale_rect_to_image((900.0, 0.0, 500.0, 100.0), 1000.0, 800.0, 1000, 800);
        assert_eq!(r, Some((900, 0, 100, 100)));
    }

    #[test]
    fn scale_rect_zero_dims_is_none() {
        assert_eq!(
            scale_rect_to_image((0.0, 0.0, 10.0, 10.0), 0.0, 800.0, 1000, 800),
            None
        );
        assert_eq!(
            scale_rect_to_image((0.0, 0.0, 10.0, 10.0), 1000.0, 800.0, 0, 800),
            None
        );
    }

    #[test]
    fn scale_rect_empty_crop_is_none() {
        // Zero-width rect → empty crop → None.
        assert_eq!(
            scale_rect_to_image((10.0, 10.0, 0.0, 50.0), 1000.0, 800.0, 1000, 800),
            None
        );
    }
}