fiptcha 0.1.1 → 0.1.3

package/README.md

@@ -187,43 +187,13 @@ Your application should remain responsible for:
 
 Fiptcha is responsible for the CAPTCHA-specific runtime: token detection, widget interaction, grid solving, model selection, model downloads, resource checks, and optional companion runtimes.
 
-## Exported helpers
-
-The package root re-exports the public exports from these modules:
-
-| Module | Purpose |
-| --- | --- |
-| `captcha-local-solver` | High-level widget/token handling and `solveLocalCaptcha`. |
-| `captcha-grid-solver` | Image-grid solving and provider adapters. |
-| `captcha-interceptor` | Challenge interception helpers. |
-| `captcha-resources` | Host/container memory and resource detection. |
-| `captcha-model-manager` | Model selection, readiness, and lifecycle state. |
-| `captcha-model-downloader` | Model download and verification. |
-| `captcha-model-manifest` | Model metadata and requirements. |
-| `captcha-companion-client` | Client for the optional companion process. |
-| `captcha-mlx-runtime` | Apple Silicon MLX runtime support. |
-| `captcha-benchmark` | Benchmarking helpers. |
-
-For example, lower-level token helpers are also available:
-
-```js
-const {
-  readToken,
-  waitForToken,
-  clickCheckbox,
-  solveLocalCaptcha
-} = require('fiptcha');
-```
-
-The high-level solver is the recommended integration boundary. Lower-level exports are useful for custom integrations, but their API should be treated as pre-stable until Fiptcha reaches a stable standalone API release.
-
 ## Models and memory requirements
 
-Fiptcha does not bundle large model weights into the npm tarball. Required assets are acquired through the model-management layer when needed.
+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. In particular, a provider-advertised **2 GB** machine is interpreted using decimal sizing (2,000,000,000 bytes, about 1907 MiB) rather than incorrectly requiring 2048 MiB.
+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 used by your deployment so models do not need to be downloaded again on every container recreation.
+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
 
@@ -247,13 +217,11 @@ Start the Docker-oriented path:
 npm run companion:start:docker
 ```
 
-The companion is optional. Ordinary Node.js integrations do not need to make it part of their architecture unless they use that runtime path.
+The companion is optional. Ordinary Node.js integrations do not need it unless they use that runtime path.
 
 ## Apple Silicon / MLX
 
-Fiptcha contains the MLX worker and runtime integration used for compatible Apple Silicon environments.
-
-The MLX path is optional. Consumers that do not use MLX can ignore the bundled worker and companion requirements.
+Fiptcha supports an optional MLX runtime for compatible Apple Silicon environments. Consumers that do not use MLX can ignore it.
 
 ## Inspect the runtime environment
 
@@ -265,43 +233,6 @@ npm run probe
 
 This is useful in containers and VMs where cgroup/container limits may differ from the physical host's reported memory.
 
-## Test Fiptcha
-
-```bash
-npm test
-```
-
-The smoke suite checks the extracted runtime and includes regression coverage for resource selection, including the 2 GB memory threshold.
-
-## Check what npm will publish
-
-Before publishing a release:
-
-```bash
-npm pack --dry-run
-```
-
-The package intentionally publishes the runtime source, entry point, companion scripts, README, and license—not downloaded model weights.
-
-## Release process
-
-Fiptcha publishes to npm as:
-
-```text
-fiptcha
-```
-
-The repository uses npm Trusted Publishing through GitHub Actions. Releases are published without a long-lived npm token.
-
-To release a new version:
-
-1. Update `version` in `package.json`.
-2. Merge the change to `main`.
-3. Create and publish a GitHub Release whose tag matches the package version, for example `v0.2.0`.
-4. The release workflow runs the tests and publishes the package to npm through OIDC Trusted Publishing.
-
-Do not manually add an `NPM_TOKEN` secret for the normal release path.
-
 ## Using Fiptcha from another project
 
 Install it normally:
@@ -325,12 +256,6 @@ async function solve(page) {
 
 No Figranium task schema, server, UI, database, scheduler, authentication system, or storage layer is required.
 
-## Using Fiptcha in Figranium
-
-Figranium consumes the published `fiptcha` package and keeps only Figranium-specific integration code in the main application.
-
-The standalone Fiptcha repository is the canonical implementation of the local CAPTCHA runtime. Fixes to model handling, resource detection, challenge interaction, or companion behavior should be made here rather than copied back into Figranium.
-
 ## Troubleshooting
 
 ### `Local solver does not support ...`
@@ -359,26 +284,6 @@ Increase the solve timeout and collect the `logs` array. Also verify that the ch
 
 Persist the model/cache storage used by the runtime instead of recreating it with every ephemeral container.
 
-### A lower-level helper changed between releases
-
-Prefer `solveLocalCaptcha` for application integrations. Until the low-level API is declared stable, pin an exact Fiptcha version if you depend directly on internal/model/grid helpers.
-
-## Package contents
-
-The npm package contains:
-
-```text
-index.js
-src/
-scripts/captcha-mlx-worker.py
-scripts/captcha-companion-requirements.txt
-scripts/captcha-container-probe.js
-scripts/install-captcha-companion.js
-scripts/captcha-companion.js
-README.md
-LICENSE
-```
-
 ## License
 
 Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiptcha",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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

@@ -1,4 +1,5 @@
 const { captchaModelManager, checksumBuffer } = require('./captcha-model-manager');
+const { clickVisibleTarget } = require('./captcha-pointer');
 
 const PROVIDERS = Object.freeze({
     recaptcha_v2: Object.freeze({
@@ -42,6 +43,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 +93,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 +122,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 +146,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) {
@@ -141,13 +161,17 @@ async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs
             const count = await cells.count();
             if (![9, 16].includes(count)) throw new Error(`Unsupported ${captchaType} grid size (${count} cells)`);
             const selected = await classifyGrid(frame, adapter, cells, prompt, seenTiles);
-            for (const index of selected) await cells.nth(index).click({ timeout: 2000 });
+            for (const index of selected) {
+                const clicked = await clickVisibleTarget(page, cells.nth(index));
+                if (!clicked) throw new Error(`${captchaType} grid tile was outside the viewport`);
+            }
             totalSelections += selected.length;
             if (!selected.length) break;
             await page.waitForTimeout(600);
         }
         logs.push(`Local ${captchaType} grid round ${round + 1}: selected ${totalSelections} cells for "${prompt}"`);
-        await frame.locator(totalSelections ? adapter.submit : adapter.noMatch).first().click({ timeout: 2000 });
+        const submitted = await clickVisibleTarget(page, frame.locator(totalSelections ? adapter.submit : adapter.noMatch).first());
+        if (!submitted) throw new Error(`${captchaType} verification button was outside the viewport`);
         const token = await waitForToken(page, captchaType, Math.min(2500, Math.max(0, deadline - Date.now())));
         if (token) return token;
         await page.waitForTimeout(350);
@@ -155,4 +179,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

@@ -1,5 +1,6 @@
 const { captchaModelManager } = require('./captcha-model-manager');
 const { solveImageGrid, PROVIDERS } = require('./captcha-grid-solver');
+const { clickVisibleTarget } = require('./captcha-pointer');
 
 const TOKEN_SELECTORS = Object.freeze({
     recaptcha_v2: ['#g-recaptcha-response', 'textarea[name="g-recaptcha-response"]'],
@@ -95,8 +96,7 @@ async function clickCheckbox(page, captchaType, timeout = 10_000) {
                     }).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);
+                    const clicked = await clickVisibleTarget(page, checkbox).catch(() => false);
                     if (clicked) return true;
                 }
             }

package/src/captcha-pointer.js

@@ -0,0 +1,31 @@
+async function viewportSize(page) {
+    const configured = page.viewportSize?.();
+    if (configured?.width && configured?.height) return configured;
+    return page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight })).catch(() => null);
+}
+
+function isInsideViewport(box, viewport) {
+    if (!box || !viewport) return false;
+    const x = box.x + (box.width / 2);
+    const y = box.y + (box.height / 2);
+    return Number.isFinite(x) && Number.isFinite(y)
+        && x >= 0 && y >= 0 && x <= viewport.width && y <= viewport.height;
+}
+
+/**
+ * Dispatch a trusted pointer click without Playwright's scroll-into-view step.
+ * CAPTCHA widgets should already be visible to a human; scrolling the page to
+ * satisfy a locator can move or invalidate the challenge between tile clicks.
+ */
+async function clickVisibleTarget(page, locator) {
+    if (!page?.mouse?.click) return false;
+    const [box, viewport] = await Promise.all([
+        locator.boundingBox().catch(() => null),
+        viewportSize(page)
+    ]);
+    if (!isInsideViewport(box, viewport)) return false;
+    await page.mouse.click(box.x + (box.width / 2), box.y + (box.height / 2));
+    return true;
+}
+
+module.exports = { clickVisibleTarget, isInsideViewport };