fiptcha 0.1.0 → 0.1.2

package/README.md

@@ -1,139 +1,203 @@
 # Fiptcha
 
-Local, self-hosted CAPTCHA solving primitives for browser automation. Built for Figranium, designed to be usable by other Node.js browser automation projects.
+[![npm version](https://img.shields.io/npm/v/fiptcha.svg)](https://www.npmjs.com/package/fiptcha)
 
-Fiptcha is the standalone CAPTCHA runtime extracted from Figranium. It contains the local model/runtime layer that Figranium uses to detect resources, manage vision models, solve image grids, interact with browser challenges, and optionally use an Apple Silicon MLX companion.
+Local CAPTCHA solving for browser automation.
 
-Fiptcha does **not** require the Figranium application or task format. The package exposes its solver modules directly, so another application can integrate the pieces it needs around its own browser lifecycle.
+Fiptcha is the lightweight CAPTCHA runtime used by Figranium, packaged as a standalone Apache-2.0 Node.js library so it can be embedded in other browser automation projects.
 
-## Why Fiptcha?
+## Install
 
-CAPTCHA solving inside a browser automation project tends to grow into its own subsystem: model selection, model downloads, resource checks, image-grid interpretation, challenge interception, browser interaction, platform-specific acceleration, and lifecycle management all need to work together. Fiptcha keeps that subsystem separate from the automation framework using it.
+```bash
+npm install fiptcha
+```
+
+CommonJS:
+
+```js
+const { solveLocalCaptcha } = require('fiptcha');
+```
 
-The goals are:
+Fiptcha does not launch a browser for you. Your application owns the browser lifecycle and passes an active Playwright-compatible `page` into the solver.
 
-- keep local CAPTCHA solving self-hostable;
-- avoid coupling the solver to Figranium's UI, API, task schema, or storage layer;
-- expose reusable Node.js modules for other browser automation projects;
-- download model assets only when they are needed rather than bundling large weights;
-- select an appropriate local backend based on available resources;
-- support optional companion runtimes without making them mandatory for every installation.
+## Quick start
+
+```js
+const { chromium } = require('playwright');
+const { solveLocalCaptcha } = require('fiptcha');
 
-## Supported challenge families
+const browser = await chromium.launch({ headless: false });
+const page = await browser.newPage();
 
-Fiptcha contains the local runtime used by Figranium for:
+await page.goto('https://example.com');
 
-- reCAPTCHA v2 image challenges;
-- hCaptcha image challenges;
-- Cloudflare Turnstile/browser challenge helpers.
+const logs = [];
+const result = await solveLocalCaptcha(page, {
+  captchaType: 'recaptcha_v2',
+  timeout: 60_000,
+  logs
+});
 
-Support is intentionally described as challenge/runtime support rather than a guarantee that every CAPTCHA can be solved. Providers change their challenge implementations and may use additional risk signals beyond the visible challenge.
+console.log(result.token);
+console.log(result.provider); // "local"
+console.log(result.model);    // present when a vision model was used
+console.log(result.device);   // "browser", "cpu", or the active inference device
 
-## Features
+await browser.close();
+```
 
-- Local CAPTCHA solving from a browser automation session.
-- Resource-aware model selection.
-- Verified, on-demand model downloads and model lifecycle management.
-- Image-grid classification and challenge handling.
-- Browser challenge interception helpers.
-- Companion-process client and runtime support.
-- Optional MLX acceleration for compatible Apple Silicon environments.
-- Container/resource probing utilities.
-- CAPTCHA benchmarking helpers.
-- Environment-variable configuration through the `CAPTCHA_*` settings used by the runtime.
-- Apache-2.0 licensing for reuse in other applications.
+## Supported challenge types
 
-## Requirements
+Pass one of these values as `captchaType`:
 
-Fiptcha is a Node.js package and expects the host application to provide the browser/page object used for challenge interaction. It does not launch or manage your entire automation application for you.
+| Value | Behavior |
+| --- | --- |
+| `recaptcha_v2` | Interacts with the checkbox and solves supported image-grid challenges locally when required. |
+| `hcaptcha` | Interacts with the widget and solves supported image-grid challenges locally when required. |
+| `turnstile` | Performs active-browser interaction and waits for a token. It does not use the image-grid vision path. |
 
-Model inference can require substantial memory. Fiptcha performs resource detection before selecting a local model. A provider-advertised 2 GB host is treated using decimal gigabyte semantics rather than incorrectly requiring a full 2 GiB/2048 MiB allocation.
+Fiptcha cannot guarantee that every challenge will be solvable. CAPTCHA providers can change their UI, challenge format, and risk checks independently of the visible widget.
 
-Large model files are not intended to be embedded into the npm package. They are fetched by the model-management layer when required.
+## `solveLocalCaptcha(page, options)`
 
-## Installation
+This is the main integration API.
 
-```bash
-npm install fiptcha
+```js
+const result = await solveLocalCaptcha(page, {
+  captchaType: 'hcaptcha',
+  timeout: 60_000,
+  logs: []
+});
 ```
 
-The package entry point is CommonJS, so it can be loaded with `require()` directly.
+### Arguments
+
+#### `page`
+
+An active Playwright-compatible page. Fiptcha uses page/frame APIs, locators, mouse interaction, evaluation, and timeouts against this object.
+
+#### `options.captchaType`
+
+Required. One of:
+
+```text
+recaptcha_v2
+hcaptcha
+turnstile
+```
+
+#### `options.timeout`
+
+Optional. Maximum solve time in milliseconds.
+
+Default:
 
 ```js
-const fiptcha = require('fiptcha');
+60_000
 ```
 
-## Basic usage
+#### `options.logs`
 
-The highest-level local solver can be used with a compatible browser page:
+Optional array. Fiptcha appends diagnostic messages to it while solving.
 
 ```js
-const { solveLocalCaptcha } = require('fiptcha');
+const logs = [];
 
-const result = await solveLocalCaptcha(page, {
+await solveLocalCaptcha(page, {
   captchaType: 'recaptcha_v2',
-  timeout: 60_000
+  logs
 });
 
-console.log(result);
+console.log(logs);
 ```
 
-Your application remains responsible for creating the browser, navigating to the target page, deciding when a solve should occur, and handling the solve result in its own workflow.
+### Return value
 
-## Integration model
+A successful solve returns an object similar to:
 
-Fiptcha is designed as a runtime library rather than a complete automation framework. A typical integration looks like this:
+```js
+{
+  token: '...',
+  provider: 'local',
+  model: 'owlvit', // only when a vision backend was used
+  device: 'cpu'
+}
+```
 
-```text
-Your application
-    |
-    +-- browser lifecycle (Playwright/compatible host)
-    |
-    +-- challenge detection / solve trigger
-    |       |
-    |       +-- Fiptcha
-    |             +-- resource detection
-    |             +-- model manager
-    |             +-- model downloader
-    |             +-- local solver
-    |             +-- grid solver
-    |             +-- optional companion / MLX runtime
-    |
-    +-- application-specific result handling
-```
-
-This separation is deliberate. Fiptcha does not know about Figranium Tasks, blocks, Cabinets, executions, authentication, scheduling, or its UI.
-
-## Public API
-
-The root package currently re-exports the public functions from the following modules:
-
-- `captcha-local-solver` — high-level local solving logic;
-- `captcha-grid-solver` — image-grid solving primitives;
-- `captcha-interceptor` — browser/challenge interception helpers;
-- `captcha-resources` — host/container resource detection;
-- `captcha-model-manager` — model selection and lifecycle management;
-- `captcha-model-downloader` — model acquisition and verification;
-- `captcha-model-manifest` — model metadata;
-- `captcha-companion-client` — communication with the optional companion process;
-- `captcha-mlx-runtime` — MLX runtime integration;
-- `captcha-benchmark` — benchmark helpers.
-
-For example:
+`model` is omitted when no vision model was needed.
+
+### Errors
+
+`solveLocalCaptcha` throws when:
+
+- the requested CAPTCHA type is unsupported;
+- a challenge never exposes a usable token or image challenge;
+- a required vision backend cannot be prepared;
+- the challenge ends without producing a token;
+- Turnstile does not issue a token after browser interaction.
+
+Wrap solves in your application's normal error handling:
 
 ```js
-const {
-  solveLocalCaptcha,
-  // Other model, resource, interception, and grid helpers are
-  // exported from the same package entry point.
-} = require('fiptcha');
+try {
+  const result = await solveLocalCaptcha(page, {
+    captchaType: 'recaptcha_v2',
+    timeout: 60_000
+  });
+
+  console.log(result.token);
+} catch (error) {
+  console.error('CAPTCHA solve failed:', error.message);
+}
 ```
 
-Fiptcha is still young, so applications that depend on lower-level helpers should pin the package version while the standalone API is being stabilized.
+## Browser integration pattern
+
+A typical integration should keep orchestration outside Fiptcha:
+
+```js
+const { solveLocalCaptcha } = require('fiptcha');
+
+async function handleCaptcha(page, captchaType) {
+  const logs = [];
+
+  const result = await solveLocalCaptcha(page, {
+    captchaType,
+    timeout: 60_000,
+    logs
+  });
+
+  return {
+    token: result.token,
+    diagnostics: logs
+  };
+}
+```
+
+Your application should remain responsible for:
+
+- launching and closing browsers;
+- choosing browser contexts and sessions;
+- navigation;
+- deciding when CAPTCHA handling should run;
+- retries at the workflow level;
+- proxies and network policy;
+- persistence;
+- translating Fiptcha errors/results into your own execution model.
+
+Fiptcha is responsible for the CAPTCHA-specific runtime: token detection, widget interaction, grid solving, model selection, model downloads, resource checks, and optional companion runtimes.
+
+## Models and memory requirements
+
+Fiptcha does not bundle large model weights into the npm package. Required assets are acquired when needed.
+
+The runtime chooses an appropriate backend based on available resources. A provider-advertised **2 GB** machine is interpreted using decimal sizing (2,000,000,000 bytes, about 1907 MiB) rather than requiring 2048 MiB.
+
+If your application runs in an ephemeral container, persist the model/cache directory so models do not need to be downloaded again on every container recreation.
 
 ## Companion runtime
 
-Fiptcha includes the companion tooling that was previously embedded in Figranium.
+Fiptcha includes an optional companion process for environments that need it.
 
 Install companion requirements:
 
@@ -141,103 +205,85 @@ Install companion requirements:
 npm run companion:install
 ```
 
-Start the companion:
+Start it:
 
 ```bash
 npm run companion:start
 ```
 
-For the Docker-oriented path:
+Start the Docker-oriented path:
 
 ```bash
 npm run companion:start:docker
 ```
 
-The companion is optional. Applications that do not need that backend can use the ordinary Node.js runtime without making the companion part of their own product architecture.
+The companion is optional. Ordinary Node.js integrations do not need it unless they use that runtime path.
 
-## Resource probing
+## Apple Silicon / MLX
 
-The package includes a probe command:
+Fiptcha supports an optional MLX runtime for compatible Apple Silicon environments. Consumers that do not use MLX can ignore it.
+
+## Inspect the runtime environment
+
+Run the included resource probe:
 
 ```bash
 npm run probe
 ```
 
-This is useful when validating the environment Fiptcha will run in, especially inside containers where reported memory limits may differ from the physical host.
-
-Resource detection is kept inside Fiptcha so applications embedding it do not need to reproduce Figranium-specific hardware checks.
-
-## Model management
-
-Fiptcha separates model metadata, downloading, resource selection, and inference/runtime behavior. This allows the package to choose a suitable backend without forcing every application to ship every supported model.
+This is useful in containers and VMs where cgroup/container limits may differ from the physical host's reported memory.
 
-The model downloader verifies model assets against the package's model manifest. Applications embedding Fiptcha should persist the configured model/cache directory if they do not want model assets to be downloaded again when an ephemeral container is recreated.
+## Using Fiptcha from another project
 
-## Configuration
+Install it normally:
 
-Fiptcha uses the `CAPTCHA_*` environment-variable configuration inherited from the standalone runtime extracted from Figranium. Configuration belongs to the process embedding Fiptcha; the package does not require a Figranium settings database.
-
-When integrating Fiptcha into another application, keep CAPTCHA/model configuration at the application boundary and pass browser state through the solver APIs rather than importing Figranium-specific configuration code.
+```bash
+npm install fiptcha
+```
 
-## Using Fiptcha outside Figranium
+Then keep the integration at your browser/runtime boundary:
 
-Fiptcha is intentionally licensed and packaged for this use case. A third-party automation project can install `fiptcha`, provide its own browser page, call the high-level solver or lower-level exported helpers, and keep its own orchestration around the package.
+```js
+const { solveLocalCaptcha } = require('fiptcha');
 
-A good integration should generally:
+async function solve(page) {
+  return solveLocalCaptcha(page, {
+    captchaType: 'recaptcha_v2',
+    timeout: 45_000
+  });
+}
+```
 
-1. let the host application own browser creation and navigation;
-2. detect or decide when a CAPTCHA needs to be handled;
-3. invoke Fiptcha with the active page/challenge context;
-4. allow Fiptcha to manage its local model/runtime concerns;
-5. translate the returned result into the host application's own success/error model.
+No Figranium task schema, server, UI, database, scheduler, authentication system, or storage layer is required.
 
-Avoid copying Fiptcha source into the consuming project. Depending on the package keeps fixes to model handling, resource detection, and challenge logic independently upgradeable.
+## Troubleshooting
 
-## Figranium integration
+### `Local solver does not support ...`
 
-Figranium consumes Fiptcha as a dependency. Compatibility shims in Figranium preserve its previous internal CAPTCHA import paths while the implementation itself lives here.
+Check that `captchaType` is exactly one of:
 
-That means Fiptcha is not merely a separately published copy of the solver: this repository is intended to be the canonical implementation of the local CAPTCHA runtime used by Figranium.
+```text
+recaptcha_v2
+hcaptcha
+turnstile
+```
 
-## Testing
+### `vision backend unavailable`
 
-Run the package smoke tests with:
+The challenge requires the image-solving path, but Fiptcha could not prepare a supported vision backend. Check available memory, model availability/downloads, and the output of:
 
 ```bash
-npm test
+npm run probe
 ```
 
-The test suite includes regression coverage for resource detection, including the 2 GB host threshold that previously rejected machines advertised as having 2 GB RAM because the check effectively required 2 GiB.
-
-## Current maturity
-
-Fiptcha began as an extraction of a production subsystem rather than a greenfield SDK. The underlying solver has already been exercised through Figranium, but the standalone package API is new.
-
-The high-level integration boundary is usable today. The main area that should be considered pre-stable is the exact shape and naming of lower-level exported helpers. Until a stable standalone API is declared, pinning an exact Fiptcha version is recommended for third-party applications.
-
-## Security and responsible use
-
-CAPTCHA systems are one part of a site's abuse-prevention and access-control strategy. Integrators are responsible for ensuring their automation is authorized and complies with applicable terms, policies, and law.
-
-Do not treat successful CAPTCHA handling as permission to access data or perform actions that the application is otherwise not authorized to perform.
-
-## Relationship to Figranium
-
-Fiptcha is part of the Figranium ecosystem but is independently reusable. Figranium provides the visual browser-automation product and orchestration layer; Fiptcha focuses on the CAPTCHA-solving runtime.
-
-## Contributing
+### Challenge appears but no token is returned
 
-Bug reports and focused improvements are welcome. For solver bugs, include enough environment information to reproduce the issue, particularly:
+Increase the solve timeout and collect the `logs` array. Also verify that the challenge family still matches the provider structure expected by the current Fiptcha version.
 
-- operating system and architecture;
-- Node.js version;
-- container/runtime details if applicable;
-- available memory;
-- CAPTCHA provider/challenge family;
-- whether the ordinary runtime or companion/MLX path was used.
+### Models download repeatedly in containers
 
-Please avoid attaching sensitive cookies, credentials, or private browsing data to public issues.
+Persist the model/cache storage used by the runtime instead of recreating it with every ephemeral container.
 
 ## License
 
-Fiptcha is licensed under the Apache License 2.0. See `LICENSE` for the full terms.
+Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiptcha",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local CAPTCHA solving for browser automation. Built for Figranium, usable anywhere.",
   "main": "index.js",
   "license": "Apache-2.0",

package/src/captcha-grid-solver.js

@@ -42,6 +42,17 @@ function normalizePrompt(adapter, text) {
     return adapter.cleanPrompt(String(text || '')).replace(/\s+/g, ' ').replace(/[.!]+$/, '').trim();
 }
 
+function normalizeModelLabel(label) {
+    return String(label || '').replace(/\b[a-z]+\b/gi, (word) => {
+        const lower = word.toLowerCase();
+        if (lower === 'buses') return 'bus';
+        if (lower.endsWith('ies')) return `${lower.slice(0, -3)}y`;
+        if (/(?:ches|shes|xes|zes)$/.test(lower)) return lower.slice(0, -2);
+        if (lower.endsWith('s') && !lower.endsWith('ss') && !lower.endsWith('us')) return lower.slice(0, -1);
+        return lower;
+    });
+}
+
 function normalizeBox(detection) {
     const box = detection?.box || detection?.bbox;
     if (Array.isArray(box) && box.length >= 4) {
@@ -81,16 +92,16 @@ function mapDetectionsToCells(detections, gridBox, cellBoxes, imageSize = null)
 }
 
 async function classifyGrid(frame, adapter, cells, label, seenTiles) {
+    const modelLabel = normalizeModelLabel(label);
     const grid = frame.locator(adapter.grid).first();
     const gridBox = await grid.boundingBox().catch(() => null);
     if (gridBox) {
         const image = await grid.screenshot({ type: 'png' });
-        const detections = await captchaModelManager.detect(image, label);
-        if (detections.length === 0) return [];
+        const detections = await captchaModelManager.detect(image, modelLabel);
         const cellBoxes = [];
         for (let index = 0; index < await cells.count(); index += 1) cellBoxes.push(await cells.nth(index).boundingBox().catch(() => null));
         const mapped = mapDetectionsToCells(detections, gridBox, cellBoxes, pngDimensions(image));
-        if (mapped.length || detections.every((item) => normalizeBox(item))) {
+        if (mapped.length) {
             const changed = [];
             for (const index of mapped) {
                 const image = await cells.nth(index).screenshot({ type: 'png' });
@@ -110,13 +121,19 @@ async function classifyGrid(frame, adapter, cells, label, seenTiles) {
         const fingerprint = checksumBuffer(image);
         if (seenTiles.get(index) === fingerprint) continue;
         seenTiles.set(index, fingerprint);
-        if ((await captchaModelManager.detect(image, label)).length) selected.push(index);
+        if ((await captchaModelManager.detect(image, modelLabel)).length) selected.push(index);
     }
     return selected;
 }
 
 async function visibleText(frame, selector) {
-    return frame.locator(selector).first().innerText({ timeout: 1500 }).catch(() => '');
+    const matches = frame.locator(selector);
+    for (let index = 0; index < await matches.count().catch(() => 0); index += 1) {
+        const locator = matches.nth(index);
+        if (!await locator.isVisible({ timeout: 250 }).catch(() => false)) continue;
+        return locator.innerText({ timeout: 1500 }).catch(() => '');
+    }
+    return '';
 }
 
 async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs = [] }) {
@@ -128,7 +145,9 @@ async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs
         const frame = await findChallengeFrame(page, adapter);
         if (!frame) throw new Error(`${captchaType} image challenge frame disappeared`);
         const rejection = await visibleText(frame, adapter.error);
-        if (rejection) throw new Error(`${captchaType} rejected the previous selection: ${rejection.replace(/\s+/g, ' ').trim()}`);
+        if (rejection && round > 0) {
+            throw new Error(`${captchaType} rejected the previous selection: ${rejection.replace(/\s+/g, ' ').trim()}`);
+        }
         const prompt = normalizePrompt(adapter, await visibleText(frame, adapter.instruction));
         if (!prompt) throw new Error(`${captchaType} solver could not read the image challenge instruction`);
         if (prompt !== previousPrompt) {
@@ -155,4 +174,4 @@ async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs
     return null;
 }
 
-module.exports = { PROVIDERS, normalizePrompt, normalizeBox, pngDimensions, mapDetectionsToCells, solveImageGrid };
+module.exports = { PROVIDERS, normalizePrompt, normalizeModelLabel, normalizeBox, pngDimensions, mapDetectionsToCells, classifyGrid, visibleText, solveImageGrid };

package/src/captcha-local-solver.js

@@ -7,6 +7,21 @@ const TOKEN_SELECTORS = Object.freeze({
     turnstile: ['input[name="cf-turnstile-response"]', 'textarea[name="cf-turnstile-response"]']
 });
 
+const WIDGET_INTERACTIONS = Object.freeze({
+    recaptcha_v2: Object.freeze({
+        framePatterns: ['/recaptcha/api2/anchor', '/recaptcha/enterprise/anchor'],
+        selectors: ['#recaptcha-anchor', '[role="checkbox"]']
+    }),
+    hcaptcha: Object.freeze({
+        framePatterns: ['hcaptcha.com/captcha', 'newassets.hcaptcha.com/captcha'],
+        selectors: ['#checkbox', '[role="checkbox"]', 'input[type="checkbox"]', 'label']
+    }),
+    turnstile: Object.freeze({
+        framePatterns: ['challenges.cloudflare.com'],
+        selectors: ['[role="checkbox"]', 'input[type="checkbox"]', 'label', 'button']
+    })
+});
+
 async function readToken(page, captchaType) {
     return page.evaluate(({ type, selectors }) => {
         for (const selector of selectors[type] || []) {
@@ -57,43 +72,40 @@ async function waitForTokenOrChallenge(page, captchaType, timeout) {
     return null;
 }
 
-async function clickCheckbox(page, captchaType) {
-    const patterns = captchaType === 'hcaptcha'
-        ? ['hcaptcha.com/captcha', 'newassets.hcaptcha.com/captcha']
-        : captchaType === 'turnstile'
-            ? ['challenges.cloudflare.com']
-            : ['/recaptcha/api2/anchor', '/recaptcha/enterprise/anchor'];
-    const selector = captchaType === 'hcaptcha'
-        ? '#checkbox, [role="checkbox"], input[type="checkbox"], label'
-        : captchaType === 'turnstile'
-            ? 'input[type="checkbox"], [role="checkbox"], button, label'
-            : '#recaptcha-anchor, [role="checkbox"]';
-    for (const frame of page.frames?.() || []) {
-        if (!patterns.some((pattern) => frame.url().includes(pattern))) continue;
-        const checkbox = frame.locator(selector).first();
-        if (!await checkbox.isVisible({ timeout: 1000 }).catch(() => false)) continue;
-        if (!await checkbox.isEnabled({ timeout: 250 }).catch(() => true)) continue;
-        const pointerReady = await checkbox.evaluate((element) => {
-            const style = getComputedStyle(element);
-            return style.pointerEvents !== 'none' && element.getAttribute('aria-disabled') !== 'true';
-        }).catch(() => true);
-        if (!pointerReady) continue;
-        const firstBox = await checkbox.boundingBox().catch(() => null);
-        await page.waitForTimeout(75);
-        const box = await checkbox.boundingBox().catch(() => null);
-        if (firstBox && box && (Math.abs(firstBox.x - box.x) >= 1 || Math.abs(firstBox.y - box.y) >= 1)) continue;
-        if (box && page.mouse) {
-            const x = box.x + box.width / 2;
-            const y = box.y + box.height / 2;
-            await page.mouse.move(x, y, { steps: 8 });
-            await page.mouse.down();
-            await page.waitForTimeout(45);
-            await page.mouse.up();
-        } else {
-            await checkbox.click({ timeout: 2000 });
+async function clickCheckbox(page, captchaType, timeout = 10_000) {
+    const interaction = WIDGET_INTERACTIONS[captchaType];
+    if (!interaction) return false;
+    const deadline = Date.now() + Math.max(0, timeout);
+
+    do {
+        for (const frame of page.frames?.() || []) {
+            const frameUrl = String(frame.url?.() || '');
+            if (!interaction.framePatterns.some((pattern) => frameUrl.includes(pattern))) continue;
+
+            for (const selector of interaction.selectors) {
+                const matches = frame.locator(selector);
+                const count = await matches.count().catch(() => 0);
+                for (let index = 0; index < count; index += 1) {
+                    const checkbox = matches.nth(index);
+                    if (!await checkbox.isVisible({ timeout: 100 }).catch(() => false)) continue;
+                    if (!await checkbox.isEnabled({ timeout: 100 }).catch(() => true)) continue;
+                    const pointerReady = await checkbox.evaluate((element) => {
+                        const style = getComputedStyle(element);
+                        return style.pointerEvents !== 'none' && element.getAttribute('aria-disabled') !== 'true';
+                    }).catch(() => true);
+                    if (!pointerReady) continue;
+
+                    const clickTimeout = Math.max(1, Math.min(2000, deadline - Date.now()));
+                    const clicked = await checkbox.click({ timeout: clickTimeout }).then(() => true, () => false);
+                    if (clicked) return true;
+                }
+            }
         }
-        return true;
-    }
+
+        if (Date.now() >= deadline) break;
+        await page.waitForTimeout(Math.min(100, Math.max(1, deadline - Date.now())));
+    } while (Date.now() <= deadline);
+
     return false;
 }
 
@@ -121,7 +133,15 @@ async function solveLocalCaptcha(page, { captchaType, timeout = 60_000, logs = [
         : null;
     let token = await readToken(page, captchaType);
     if (!token) {
-        await clickCheckbox(page, captchaType).catch((error) => logs.push(`Local ${captchaType} checkbox click failed: ${error.message}`));
+        const clickTimeout = Math.min(10_000, Math.max(0, deadline - Date.now()));
+        const clicked = await clickCheckbox(page, captchaType, clickTimeout)
+            .catch((error) => {
+                logs.push(`Local ${captchaType} checkbox click failed: ${error.message}`);
+                return false;
+            });
+        logs.push(clicked
+            ? `Local ${captchaType} checkbox clicked`
+            : `Local ${captchaType} checkbox was not found before the interaction timeout`);
         const initialWait = captchaType === 'hcaptcha' ? 1500 : 7000;
         token = await waitForTokenOrChallenge(page, captchaType, Math.min(initialWait, Math.max(0, deadline - Date.now())));
         if (!token && captchaType === 'hcaptcha' && Date.now() < deadline) {
@@ -165,4 +185,4 @@ async function solveLocalCaptcha(page, { captchaType, timeout = 60_000, logs = [
     };
 }
 
-module.exports = { TOKEN_SELECTORS, readToken, waitForToken, waitForTokenOrChallenge, clickCheckbox, executeHcaptchaWidget, solveLocalCaptcha };
+module.exports = { TOKEN_SELECTORS, WIDGET_INTERACTIONS, readToken, waitForToken, waitForTokenOrChallenge, clickCheckbox, executeHcaptchaWidget, solveLocalCaptcha };