fiptcha 0.1.0

package/scripts/captcha-companion.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+process.env.CAPTCHA_COMPANION_MODE = 'true';
+process.env.CAPTCHA_DISABLE_COMPANION = 'true';
+process.env.CAPTCHA_MODEL_DEVICE = process.env.CAPTCHA_MODEL_DEVICE || 'auto';
+
+const { captchaModelManager, selectModelTier, getMemorySnapshot, parseFlag } = require('../src/captcha-model-manager');
+const { TOKEN_FILE, DEFAULT_PORT } = require('../src/captcha-companion-client');
+const { loadVerifiedMlxRuntime } = require('../src/captcha-mlx-runtime');
+
+const dockerMode = process.argv.includes('--docker');
+const host = dockerMode ? '0.0.0.0' : '127.0.0.1';
+const port = Number(process.env.CAPTCHA_COMPANION_PORT || DEFAULT_PORT);
+const MAX_BODY_BYTES = 7 * 1024 * 1024;
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const INFERENCE_TIMEOUT_MS = Number(process.env.CAPTCHA_COMPANION_INFERENCE_TIMEOUT_MS || 45_000);
+let detectQueue = Promise.resolve();
+const modelRoot = path.resolve(process.env.CAPTCHA_MODEL_CACHE_DIR || path.join(process.cwd(), 'data', 'captcha-model'));
+let activeMlx = null;
+let initializationError = null;
+
+function ensureToken() {
+    const configured = String(process.env.CAPTCHA_COMPANION_TOKEN || '').trim();
+    if (configured) return;
+    fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+    if (!fs.existsSync(TOKEN_FILE)) fs.writeFileSync(TOKEN_FILE, `${crypto.randomBytes(32).toString('hex')}\n`, { mode: 0o600 });
+    else fs.chmodSync(TOKEN_FILE, 0o600);
+}
+
+function readToken() {
+    const token = String(process.env.CAPTCHA_COMPANION_TOKEN || '').trim();
+    if (token) return token;
+    try { return fs.readFileSync(TOKEN_FILE, 'utf8').trim(); } catch { return ''; }
+}
+
+function sendJson(response, status, payload) {
+    const body = JSON.stringify(payload);
+    response.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body), 'Cache-Control': 'no-store' });
+    response.end(body);
+}
+
+function authorized(request) {
+    const token = readToken();
+    const supplied = String(request.headers.authorization || '');
+    const expected = `Bearer ${token}`;
+    if (!token || supplied.length !== expected.length) return false;
+    return crypto.timingSafeEqual(Buffer.from(supplied), Buffer.from(expected));
+}
+
+async function readJson(request) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) throw Object.assign(new Error('Request body too large'), { status: 413 });
+        chunks.push(chunk);
+    }
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+    catch { throw Object.assign(new Error('Malformed JSON'), { status: 400 }); }
+}
+
+function enqueueDetect(operation) {
+    const pending = detectQueue.then(operation, operation);
+    detectQueue = pending.catch(() => undefined);
+    return pending;
+}
+
+async function removeModelDirectories(names) {
+    for (const name of names) await fs.promises.rm(path.join(modelRoot, name), { recursive: true, force: true });
+}
+
+async function activateMlx() {
+    if (activeMlx) return activeMlx;
+    let runtime;
+    try {
+        runtime = await loadVerifiedMlxRuntime(modelRoot);
+    } catch (error) {
+        const enospc = error?.code === 'ENOSPC' || /ENOSPC|no space left/i.test(error?.message || '');
+        if (!enospc || !captchaModelManager.status().healthy) throw error;
+        await captchaModelManager.stop();
+        await removeModelDirectories(['owlvit', 'florence2']);
+        runtime = await loadVerifiedMlxRuntime(modelRoot);
+    }
+    const previousMlx = activeMlx;
+    activeMlx = runtime;
+    await captchaModelManager.stop();
+    await removeModelDirectories(['owlvit', 'florence2']);
+    await previousMlx?.dispose?.().catch?.(() => undefined);
+    await fs.promises.mkdir(modelRoot, { recursive: true });
+    const temporary = path.join(modelRoot, '.active.json.tmp');
+    await fs.promises.writeFile(temporary, JSON.stringify({
+        tier: 'florence2', model: 'mlx-community/Florence-2-base-ft-4bit', backend: 'companion', device: 'mlx', activatedAt: new Date().toISOString()
+    }, null, 2), { mode: 0o600 });
+    await fs.promises.rename(temporary, path.join(modelRoot, 'active.json'));
+    return runtime;
+}
+
+async function activateOnnx(tier) {
+    const previousTier = process.env.CAPTCHA_MODEL_TIER;
+    process.env.CAPTCHA_MODEL_TIER = tier;
+    try {
+        await captchaModelManager.start();
+        await captchaModelManager.reconcile();
+        if (!captchaModelManager.status().healthy) throw new Error(captchaModelManager.status().error || 'Native ONNX backend is unhealthy');
+    } finally {
+        if (previousTier === undefined) delete process.env.CAPTCHA_MODEL_TIER;
+        else process.env.CAPTCHA_MODEL_TIER = previousTier;
+    }
+    const previousMlx = activeMlx;
+    activeMlx = null;
+    await previousMlx?.dispose?.().catch?.(() => undefined);
+    await removeModelDirectories(['florence2-mlx', '.staging-florence2-mlx']);
+}
+
+async function detectTier(tier, image, label, threshold) {
+    if (tier === 'florence2' && process.env.CAPTCHA_MODEL_DEVICE !== 'cpu' && !parseFlag(process.env.CAPTCHA_COMPANION_DISABLE_MLX)) {
+        try {
+            const runtime = await activateMlx();
+            return { detections: await runtime.detect(image, label, threshold), backend: 'companion', device: 'mlx' };
+        } catch (error) {
+            initializationError = `MLX unavailable; using native ONNX: ${error.message}`;
+            console.warn(`[CAPTCHA_COMPANION] ${initializationError}`);
+        }
+    }
+    await activateOnnx(tier);
+    const previousTier = process.env.CAPTCHA_MODEL_TIER;
+    process.env.CAPTCHA_MODEL_TIER = tier;
+    try {
+        const detections = await captchaModelManager.detect(image, label, threshold);
+        const status = captchaModelManager.status();
+        return { detections, backend: status.backend, device: status.device };
+    } finally {
+        if (previousTier === undefined) delete process.env.CAPTCHA_MODEL_TIER;
+        else process.env.CAPTCHA_MODEL_TIER = previousTier;
+    }
+}
+
+async function initializeCompanion() {
+    const tier = selectModelTier(getMemorySnapshot());
+    if (!tier) throw new Error('Host has insufficient available unified memory for a companion model');
+    await detectTier(tier, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAGUlEQVR4nO3BAQ0AAADCoPdPbQ43oAAAAAAAAAB4Gx4gAAE7Bq0AAAAASUVORK5CYII=', 'base64'), 'object', 0.99);
+    initializationError = null;
+}
+
+const server = http.createServer(async (request, response) => {
+    try {
+        if (!authorized(request)) return sendJson(response, 401, { error: 'UNAUTHORIZED' });
+        if (request.method === 'GET' && request.url === '/v1/health') {
+            const status = captchaModelManager.status();
+            const mlxHealthy = Boolean(activeMlx);
+            return sendJson(response, 200, {
+                ...status,
+                healthy: mlxHealthy || status.healthy,
+                activeTier: mlxHealthy ? 'florence2' : status.activeTier,
+                version: 1,
+                backend: mlxHealthy ? 'mlx' : status.device === 'coreml' ? 'coreml' : 'onnx-native',
+                error: initializationError || status.error,
+                memory: { totalMb: os.totalmem() / 1048576, availableMb: os.freemem() / 1048576 }
+            });
+        }
+        if (request.method === 'POST' && request.url === '/v1/detect') {
+            return enqueueDetect(async () => {
+                const body = await readJson(request);
+                if (!['owlvit', 'florence2'].includes(body.tier)) return sendJson(response, 400, { error: 'INVALID_TIER' });
+                if (typeof body.label !== 'string' || !body.label.trim() || typeof body.imageBase64 !== 'string') {
+                    return sendJson(response, 400, { error: 'INVALID_REQUEST' });
+                }
+                const image = Buffer.from(body.imageBase64, 'base64');
+                if (!image.length || image.length > MAX_IMAGE_BYTES) return sendJson(response, 413, { error: 'INVALID_IMAGE_SIZE' });
+                const inference = detectTier(body.tier, image, body.label.trim(), Number(body.threshold));
+                let timeoutHandle;
+                const timeout = new Promise((resolve) => {
+                    timeoutHandle = setTimeout(() => resolve({ timedOut: true }), INFERENCE_TIMEOUT_MS);
+                    timeoutHandle.unref?.();
+                });
+                const outcome = await Promise.race([
+                    inference.then((result) => ({ result }), (error) => ({ error })),
+                    timeout
+                ]);
+                clearTimeout(timeoutHandle);
+                if (outcome.timedOut) {
+                    sendJson(response, 504, { error: 'INFERENCE_TIMEOUT' });
+                    await inference.catch(() => undefined);
+                    return undefined;
+                }
+                if (outcome.error) throw outcome.error;
+                return sendJson(response, 200, outcome.result);
+            });
+        }
+        return sendJson(response, 404, { error: 'NOT_FOUND' });
+    } catch (error) {
+        return sendJson(response, error.status || 500, { error: error.message || 'COMPANION_ERROR' });
+    }
+});
+
+async function shutdown() {
+    server.close();
+    await activeMlx?.dispose?.().catch?.(() => undefined);
+    await captchaModelManager.stop().catch(() => undefined);
+    process.exit(0);
+}
+
+server.requestTimeout = Math.max(INFERENCE_TIMEOUT_MS + 5000, 50_000);
+server.headersTimeout = 10_000;
+
+if (require.main === module) {
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    ensureToken();
+    initializeCompanion().catch((error) => {
+        initializationError = error.message;
+        console.warn(`[CAPTCHA_COMPANION] Initial model probe failed: ${error.message}`);
+    });
+    server.listen(port, host, () => console.log(`[CAPTCHA_COMPANION] Listening on http://${host}:${port}`));
+}
+
+module.exports = { authorized, readJson, server };

package/scripts/captcha-container-probe.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const { captchaModelManager, getMemorySnapshot } = require('../src/captcha-model-manager');
+
+function currentUse() {
+    for (const file of ['/sys/fs/cgroup/memory.current', '/sys/fs/cgroup/memory/memory.usage_in_bytes']) {
+        try { return Number(fs.readFileSync(file, 'utf8').trim()); } catch { /* unsupported cgroup layout */ }
+    }
+    return process.memoryUsage().rss;
+}
+
+async function main() {
+    let peakBytes = currentUse();
+    const sampler = setInterval(() => { peakBytes = Math.max(peakBytes, currentUse()); }, 25);
+    try {
+        await captchaModelManager.start();
+        const status = captchaModelManager.status();
+        const expected = process.env.CAPTCHA_ACCEPT_EXPECTED_TIER || '';
+        if ((status.activeTier || '') !== expected) throw new Error(`Expected tier ${expected || 'none'}, got ${status.activeTier || 'none'}: ${status.error || ''}`);
+        console.log(JSON.stringify({ status, memory: getMemorySnapshot(), peakBytes }));
+    } finally {
+        clearInterval(sampler);
+        await captchaModelManager.stop();
+    }
+}
+
+main().catch((error) => { console.error(error); process.exit(1); });

package/scripts/captcha-mlx-worker.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+import base64
+import contextlib
+import io
+import json
+import os
+import sys
+import traceback
+
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+
+from PIL import Image
+
+
+def emit(payload):
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def extract_detections(parsed, label, threshold):
+    if not isinstance(parsed, dict):
+        return []
+    value = parsed.get("<OPEN_VOCABULARY_DETECTION>", parsed)
+    boxes = value.get("bboxes", value.get("boxes", [])) if isinstance(value, dict) else []
+    labels = value.get("labels", []) if isinstance(value, dict) else []
+    return [
+        {"box": box, "label": labels[index] if index < len(labels) else label, "score": threshold}
+        for index, box in enumerate(boxes)
+    ]
+
+
+def main():
+    if len(sys.argv) != 2:
+        raise RuntimeError("Expected a verified local model directory")
+    model_path = os.path.realpath(sys.argv[1])
+    if not os.path.isdir(model_path):
+        raise RuntimeError("Verified local MLX model directory is missing")
+    with contextlib.redirect_stdout(sys.stderr):
+        from mlx_vlm import generate, load
+        model, processor = load(model_path, lazy=False, trust_remote_code=True)
+    emit({"ready": True, "backend": "mlx"})
+    for line in sys.stdin:
+        request = json.loads(line)
+        request_id = request.get("id")
+        try:
+            image = Image.open(io.BytesIO(base64.b64decode(request["imageBase64"], validate=True))).convert("RGB")
+            label = str(request["label"]).strip()
+            threshold = float(request.get("threshold", 0.18))
+            task = f"<OPEN_VOCABULARY_DETECTION>{label}"
+            with contextlib.redirect_stdout(sys.stderr):
+                result = generate(model, processor, task, image, max_tokens=64, temperature=0.0)
+            text = result.text if hasattr(result, "text") else str(result)
+            parsed = processor.post_process_generation(text, task=task, image_size=image.size)
+            emit({"id": request_id, "detections": extract_detections(parsed, label, threshold)})
+        except Exception as error:
+            emit({"id": request_id, "error": str(error)[:500]})
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        sys.stderr.write(traceback.format_exc())
+        emit({"ready": False, "error": str(error)[:500]})
+        sys.exit(1)

package/scripts/install-captcha-companion.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+    console.error('The CAPTCHA accelerator companion requires Apple Silicon macOS.');
+    process.exit(1);
+}
+
+async function main() {
+    const ort = require('onnxruntime-node');
+    const backends = await ort.listSupportedBackends();
+    if (!backends.some((backend) => backend.name === 'coreml' && backend.bundled)) {
+        throw new Error('The installed ONNX Runtime does not include CoreMLExecutionProvider');
+    }
+    const dataDir = path.resolve(process.cwd(), 'data');
+    const environmentDir = path.join(dataDir, 'captcha-companion', 'venv');
+    const tokenFile = path.join(dataDir, 'captcha-companion-token');
+    await fs.promises.mkdir(dataDir, { recursive: true });
+    const candidates = [process.env.PYTHON, 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3'].filter(Boolean);
+    const python = candidates.find((candidate) => {
+        try {
+            const version = execFileSync(candidate, ['-c', 'import sys; print(int(sys.version_info >= (3, 10)))'], { encoding: 'utf8', timeout: 5000 }).trim();
+            return version === '1';
+        } catch { return false; }
+    });
+    if (!python) throw new Error('Python 3.10 or newer is required for the pinned MLX companion environment');
+    if (!fs.existsSync(path.join(environmentDir, 'bin', 'python3'))) {
+        execFileSync(python, ['-m', 'venv', environmentDir], { stdio: 'inherit', timeout: 120_000 });
+    }
+    execFileSync(path.join(environmentDir, 'bin', 'python3'), [
+        '-m', 'pip', 'install', '--disable-pip-version-check', '--requirement', path.join(__dirname, 'captcha-companion-requirements.txt')
+    ], { stdio: 'inherit', timeout: 15 * 60_000 });
+    const exists = await fs.promises.access(tokenFile).then(() => true).catch(() => false);
+    if (!exists) await fs.promises.writeFile(tokenFile, `${crypto.randomBytes(32).toString('hex')}\n`, { mode: 0o600 });
+    else await fs.promises.chmod(tokenFile, 0o600).catch(() => undefined);
+    console.log(`CAPTCHA companion isolated environment: ${environmentDir}`);
+    console.log(`CAPTCHA companion ready. Authentication token: ${tokenFile}`);
+    console.log('Model weights will be downloaded and verified only when the companion starts.');
+}
+
+main().catch((error) => {
+    console.error(`CAPTCHA companion installation failed: ${error.message}`);
+    process.exit(1);
+});

package/src/captcha-benchmark.js

@@ -0,0 +1,25 @@
+function metricsAtThreshold(samples, threshold) {
+    let truePositive = 0;
+    let falsePositive = 0;
+    let falseNegative = 0;
+    for (const sample of samples) {
+        const predicted = Number(sample.score) >= threshold;
+        if (predicted && sample.match) truePositive += 1;
+        else if (predicted) falsePositive += 1;
+        else if (sample.match) falseNegative += 1;
+    }
+    const recall = truePositive / Math.max(1, truePositive + falseNegative);
+    const precision = truePositive / Math.max(1, truePositive + falsePositive);
+    const f1 = (2 * precision * recall) / Math.max(Number.EPSILON, precision + recall);
+    return { threshold, truePositive, falsePositive, falseNegative, precision, recall, f1 };
+}
+
+function selectConfidenceThreshold(samples, { minimumRecall = 0.9, minimumF1 = 0.8 } = {}) {
+    const candidates = [...new Set(samples.map((sample) => Number(sample.score)).filter(Number.isFinite))].sort((a, b) => a - b);
+    const selected = candidates.map((threshold) => metricsAtThreshold(samples, threshold))
+        .find((metrics) => metrics.recall >= minimumRecall && metrics.f1 >= minimumF1);
+    if (!selected) throw new Error(`No threshold reaches recall ${minimumRecall} and F1 ${minimumF1}`);
+    return selected;
+}
+
+module.exports = { metricsAtThreshold, selectConfidenceThreshold };

package/src/captcha-companion-client.js

@@ -0,0 +1,74 @@
+const fs = require('fs');
+const path = require('path');
+
+const DATA_DIR = path.resolve(process.cwd(), 'data');
+const TOKEN_FILE = path.join(DATA_DIR, 'captcha-companion-token');
+const DEFAULT_PORT = 11438;
+
+function isDocker() {
+    return fs.existsSync('/.dockerenv') || Boolean(process.env.CONTAINER);
+}
+
+function resolveCompanionConfig(env = process.env) {
+    if (String(env.CAPTCHA_DISABLE_COMPANION || '').toLowerCase() === 'true') return null;
+    let baseUrl = String(env.CAPTCHA_COMPANION_URL || '').trim();
+    if (!baseUrl && process.platform === 'darwin') baseUrl = `http://127.0.0.1:${DEFAULT_PORT}`;
+    if (!baseUrl && isDocker()) baseUrl = `http://host.docker.internal:${DEFAULT_PORT}`;
+    if (!baseUrl) return null;
+    let parsed;
+    try { parsed = new URL(baseUrl); } catch { throw new Error('Invalid CAPTCHA_COMPANION_URL'); }
+    if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error('CAPTCHA companion URL must use HTTP or HTTPS');
+    let token = String(env.CAPTCHA_COMPANION_TOKEN || '').trim();
+    if (!token) {
+        try { token = fs.readFileSync(TOKEN_FILE, 'utf8').trim(); } catch { /* optional */ }
+    }
+    return { baseUrl: baseUrl.replace(/\/+$/, ''), token };
+}
+
+async function companionRequest(endpoint, { method = 'GET', body, timeout = 1000 } = {}) {
+    const config = resolveCompanionConfig();
+    if (!config) return null;
+    const headers = { Accept: 'application/json' };
+    if (config.token) headers.Authorization = `Bearer ${config.token}`;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const response = await fetch(`${config.baseUrl}${endpoint}`, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.timeout(timeout)
+    });
+    let payload;
+    try { payload = await response.json(); } catch { throw new Error(`Apple companion returned malformed JSON (HTTP ${response.status})`); }
+    if (!response.ok) throw new Error(payload.error || `Apple companion HTTP ${response.status}`);
+    return payload;
+}
+
+async function probeCompanion(timeout = 750) {
+    try {
+        const health = await companionRequest('/v1/health', { timeout });
+        if (!health?.healthy || !Number.isFinite(health.memory?.totalMb)) return null;
+        return health;
+    } catch {
+        return null;
+    }
+}
+
+async function detectWithCompanion(imageBuffer, label, tier, threshold, timeout = 30_000) {
+    const payload = await companionRequest('/v1/detect', {
+        method: 'POST',
+        timeout,
+        body: { tier, label, threshold, imageBase64: imageBuffer.toString('base64') }
+    });
+    if (!Array.isArray(payload?.detections)) throw new Error('Apple companion returned invalid detections');
+    return { detections: payload.detections, backend: payload.backend || 'companion', device: payload.device || 'coreml' };
+}
+
+module.exports = {
+    DEFAULT_PORT,
+    TOKEN_FILE,
+    isDocker,
+    resolveCompanionConfig,
+    companionRequest,
+    probeCompanion,
+    detectWithCompanion
+};

package/src/captcha-grid-solver.js

@@ -0,0 +1,158 @@
+const { captchaModelManager, checksumBuffer } = require('./captcha-model-manager');
+
+const PROVIDERS = Object.freeze({
+    recaptcha_v2: Object.freeze({
+        framePatterns: ['/recaptcha/api2/bframe', '/recaptcha/enterprise/bframe'],
+        instruction: '.rc-imageselect-desc-wrapper, .rc-imageselect-instructions',
+        grid: '.rc-imageselect-table-33, .rc-imageselect-table-44',
+        cells: '.rc-imageselect-tile',
+        submit: '#recaptcha-verify-button',
+        noMatch: '#recaptcha-verify-button',
+        error: '.rc-imageselect-error-select-more, .rc-imageselect-error-dynamic-more, .rc-imageselect-incorrect-response',
+        cleanPrompt(text) {
+            return text.replace(/select all (images|squares) with/ig, '')
+                .replace(/click verify once there are none left/ig, '')
+                .replace(/if there are none, click skip/ig, '');
+        }
+    }),
+    hcaptcha: Object.freeze({
+        framePatterns: ['hcaptcha.com/captcha', 'newassets.hcaptcha.com/captcha'],
+        instruction: '.prompt-text, .challenge-header .prompt-text, h2',
+        grid: '.task-grid',
+        cells: '.task-grid .task-image',
+        submit: '.button-submit, button[type="submit"]',
+        noMatch: '.button-submit, button[type="submit"]',
+        error: '.error-text, .challenge-error',
+        cleanPrompt(text) {
+            return text.replace(/please (click|select) (on )?(all|each) (the )?(images|squares) (containing|with)/ig, '')
+                .replace(/if there are none, (click|select) (skip|next)/ig, '');
+        }
+    })
+});
+
+async function findChallengeFrame(page, adapter) {
+    for (const frame of page.frames()) {
+        if (!adapter.framePatterns.some((pattern) => frame.url().includes(pattern))) continue;
+        if (await frame.locator(adapter.grid).first().isVisible({ timeout: 250 }).catch(() => false)) return frame;
+    }
+    return null;
+}
+
+function normalizePrompt(adapter, text) {
+    return adapter.cleanPrompt(String(text || '')).replace(/\s+/g, ' ').replace(/[.!]+$/, '').trim();
+}
+
+function normalizeBox(detection) {
+    const box = detection?.box || detection?.bbox;
+    if (Array.isArray(box) && box.length >= 4) {
+        const [xmin, ymin, xmax, ymax] = box.map(Number);
+        return { xmin, ymin, xmax, ymax };
+    }
+    if (box && typeof box === 'object') {
+        const xmin = Number(box.xmin ?? box.x ?? box.left);
+        const ymin = Number(box.ymin ?? box.y ?? box.top);
+        const xmax = Number(box.xmax ?? box.right ?? (Number.isFinite(xmin) ? xmin + Number(box.width) : NaN));
+        const ymax = Number(box.ymax ?? box.bottom ?? (Number.isFinite(ymin) ? ymin + Number(box.height) : NaN));
+        if ([xmin, ymin, xmax, ymax].every(Number.isFinite)) return { xmin, ymin, xmax, ymax };
+    }
+    return null;
+}
+
+function pngDimensions(buffer) {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 24 || buffer.toString('ascii', 1, 4) !== 'PNG') return null;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+function mapDetectionsToCells(detections, gridBox, cellBoxes, imageSize = null) {
+    const indexes = new Set();
+    const scaleX = imageSize?.width ? gridBox.width / imageSize.width : 1;
+    const scaleY = imageSize?.height ? gridBox.height / imageSize.height : 1;
+    for (const detection of detections) {
+        const box = normalizeBox(detection);
+        if (!box) continue;
+        const centerX = gridBox.x + (((box.xmin + box.xmax) / 2) * scaleX);
+        const centerY = gridBox.y + (((box.ymin + box.ymax) / 2) * scaleY);
+        const index = cellBoxes.findIndex((cell) => cell
+            && centerX >= cell.x && centerX <= cell.x + cell.width
+            && centerY >= cell.y && centerY <= cell.y + cell.height);
+        if (index >= 0) indexes.add(index);
+    }
+    return [...indexes];
+}
+
+async function classifyGrid(frame, adapter, cells, label, seenTiles) {
+    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 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))) {
+            const changed = [];
+            for (const index of mapped) {
+                const image = await cells.nth(index).screenshot({ type: 'png' });
+                const fingerprint = checksumBuffer(image);
+                if (seenTiles.get(index) === fingerprint) continue;
+                seenTiles.set(index, fingerprint);
+                changed.push(index);
+            }
+            return changed;
+        }
+    }
+
+    const selected = [];
+    for (let index = 0; index < await cells.count(); index += 1) {
+        const cell = cells.nth(index);
+        const image = await cell.screenshot({ type: 'png' });
+        const fingerprint = checksumBuffer(image);
+        if (seenTiles.get(index) === fingerprint) continue;
+        seenTiles.set(index, fingerprint);
+        if ((await captchaModelManager.detect(image, label)).length) selected.push(index);
+    }
+    return selected;
+}
+
+async function visibleText(frame, selector) {
+    return frame.locator(selector).first().innerText({ timeout: 1500 }).catch(() => '');
+}
+
+async function solveImageGrid(page, { captchaType, deadline, waitForToken, logs = [] }) {
+    const adapter = PROVIDERS[captchaType];
+    if (!adapter) throw new Error(`No image-grid adapter for ${captchaType}`);
+    const seenTiles = new Map();
+    let previousPrompt = '';
+    for (let round = 0; round < 6 && Date.now() < deadline; round += 1) {
+        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()}`);
+        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) {
+            seenTiles.clear();
+            previousPrompt = prompt;
+        }
+        let totalSelections = 0;
+        for (let sweep = 0; sweep < 4 && Date.now() < deadline; sweep += 1) {
+            const cells = frame.locator(adapter.cells);
+            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 });
+            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 token = await waitForToken(page, captchaType, Math.min(2500, Math.max(0, deadline - Date.now())));
+        if (token) return token;
+        await page.waitForTimeout(350);
+    }
+    return null;
+}
+
+module.exports = { PROVIDERS, normalizePrompt, normalizeBox, pngDimensions, mapDetectionsToCells, solveImageGrid };

package/src/captcha-interceptor.js

@@ -0,0 +1,39 @@
+function installTurnstileInterceptor(options = {}) {
+    const root = globalThis;
+    const state = root.__figraniumCaptcha = root.__figraniumCaptcha || {};
+    state.blockManaged = Boolean(options.blockManaged);
+
+    const wrapRender = () => {
+        const api = root.turnstile;
+        if (!api || typeof api.render !== 'function' || api.render.__figraniumWrapped) return;
+        const originalRender = api.render;
+        const wrappedRender = function (container, renderOptions = {}) {
+            const managed = Boolean(renderOptions.cData && renderOptions.chlPageData);
+            state.turnstile = {
+                siteKey: renderOptions.sitekey || null,
+                action: renderOptions.action || null,
+                cData: renderOptions.cData || null,
+                chlPageData: renderOptions.chlPageData || null,
+                callback: typeof renderOptions.callback === 'function' ? renderOptions.callback : null,
+                callbackName: typeof renderOptions.callback === 'string' ? renderOptions.callback : null,
+                container: typeof container === 'string' ? root.document?.querySelector(container) : container,
+                userAgent: navigator.userAgent,
+                managed,
+                blocked: managed && state.blockManaged,
+                readyAt: Date.now(),
+                callbackInvoked: false
+            };
+            if (managed && state.blockManaged) return `figranium-turnstile-${Date.now()}`;
+            return originalRender.apply(this, arguments);
+        };
+        Object.defineProperty(wrappedRender, '__figraniumWrapped', { value: true });
+        Object.defineProperty(wrappedRender, '__figraniumOriginal', { value: originalRender });
+        api.render = wrappedRender;
+    };
+
+    wrapRender();
+    const interval = setInterval(wrapRender, 10);
+    root.addEventListener?.('pagehide', () => clearInterval(interval), { once: true });
+}
+
+module.exports = { installTurnstileInterceptor };