captchakraken 2.9.0 → 3.0.0

package/python/src/captchakraken/tool_calls/track_piece.py

@@ -1,37 +1,8 @@
-"""Track the puzzle piece of a slide captcha by what MOVED, not by what it is.
+"""Track a slide captcha's piece by what MOVED between two shots, not by what it is.
 
-A puzzle-piece slider gives the model one thing to say — where the gap is — and
-gives the driver no way to act on it directly. You drag a handle somewhere else
-on the widget; the piece follows at a ratio nobody publishes, clamped to a track
-whose ends you cannot read off the picture. Vendors vary the ratio precisely so
-that a solver cannot compute the handle offset from the gap position.
-
-So the driver does not compute it. It presses the handle, nudges, looks at what
-changed on screen, and closes the loop. This module is the "looks at what
-changed" step, and nothing more: one function, one bounding box.
-
-    changed_bbox(before, after, exclude=...) -> [x1, y1, x2, y2] | None
-
-The box is the union of every pixel that differs between two screenshots of the
-same widget. During a slider drag exactly one thing has moved — the piece — so
-that union is:
-
-    left edge  = the piece's ORIGINAL left edge   (the vacated ground)
-    right edge = the piece's CURRENT right edge
-
-which is what makes it useful: neither edge alone gives the piece's centre, but
-two of these boxes at two known handle offsets give both the piece's width and
-the handle-to-piece ratio, by simple algebra the caller does. See
-`PageSolver._execute_slide`.
-
-`exclude` is the reason this takes an argument at all. The handle is also
-moving, and on most vendors so is a filled progress bar behind it, and both are
-inside the same screenshot. Left in, they would dominate the union and the
-tracked "piece" would just be the handle. The caller passes the handle's own
-rectangle — it has the element, so it knows exactly where it is — and this masks
-it out. Everything else in the frame is static during a drag.
-
-Pure OpenCV, no network, byte-deterministic.
+Vendors vary the handle-to-piece ratio so the offset cannot be computed from the gap, so the driver sweeps,
+looks at what changed, and corrects. The changed box's left edge is the vacated ground and its right edge the
+piece's current edge; a sweep that clears the ground leaves two marks, and the right one IS the piece.
 """
 
 from __future__ import annotations
@@ -41,33 +12,30 @@ from typing import Optional, Sequence
 import cv2
 import numpy as np
 
-# A pixel counts as changed at this 0–255 grayscale delta. Low enough to catch a
-# piece sliding over background of similar luminance, high enough to ignore JPEG
-# ringing and the 1–2 level jitter of an antialiased edge redrawn a subpixel
-# over.
+# Low enough to catch a piece over similar-luminance ground, above JPEG ringing and antialiased-edge jitter.
 _DIFF_THRESHOLD = 18
 
-# Below this many changed pixels the frame is treated as UNCHANGED. A press that
-# has not moved yet, or a drag against the end of the track, produces a handful
-# of stray pixels; calling that a piece would hand the caller a garbage box and
-# it would steer by it.
+# A press that has not moved yet leaves stray pixels; calling that a piece hands the caller a box it steers by.
 _MIN_CHANGED_PIXELS = 40
 
+# Two marks are the piece and its ghost only if they are the same object, so the same width to a quarter.
+_SAME_WIDTH_TOLERANCE = 0.25
 
-def changed_bbox(
+# Two regimes: a mark no more than half the travel is the piece, a mark of about the travel is the sliver at
+# either end of an overlap. `travel` is only believed, so the regimes have to sit far apart.
+_CLEARED_MARK_FRACTION = 0.5
+
+# A piece with a notch can go still for several columns; the two marks are a whole sweep apart.
+_MARK_GAP_PX = 10
+
+_MIN_COLUMN_PIXELS = 2
+
+
+def _change_mask(
     before_path: str,
     after_path: str,
     exclude: Optional[Sequence[float]] = None,
-) -> Optional[list]:
-    """Bounding box of everything that moved between two shots of one widget.
-
-    `exclude` is an [x1, y1, x2, y2] rectangle in the same pixel space, masked
-    out before measuring — pass the slider handle's own box.
-
-    Returns [x1, y1, x2, y2] in pixels, or None when nothing moved (or the
-    images are unreadable / mismatched, which is the same answer to the caller:
-    steer by the last good reading instead of by noise).
-    """
+):
     a = cv2.imread(before_path, cv2.IMREAD_GRAYSCALE)
     b = cv2.imread(after_path, cv2.IMREAD_GRAYSCALE)
     if a is None or b is None or a.shape != b.shape:
@@ -77,20 +45,76 @@ def changed_bbox(
 
     if exclude is not None:
         x1, y1, x2, y2 = (int(round(float(v))) for v in exclude)
-        # Clamp to the frame — a handle drawn flush with the widget edge, or one
-        # whose box is reported a pixel outside it, must still mask.
         x1, y1 = max(0, x1), max(0, y1)
         x2, y2 = min(mask.shape[1], x2), min(mask.shape[0], y2)
         if x2 > x1 and y2 > y1:
             mask[y1:y2, x1:x2] = 0
 
-    # Erode away single-pixel speckle (compression noise, cursor artifacts)
-    # before measuring: the box is an EXTREME of the mask, so one stray pixel in
-    # the corner moves it as much as the piece does.
+    # Erode speckle before measuring: the box is an EXTREME of the mask, so one stray pixel moves it as much as the piece.
     mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, np.ones((3, 3), np.uint8))
 
     if int(mask.sum()) < _MIN_CHANGED_PIXELS:
         return None
+    return mask
+
+
+def _marks(mask) -> list:
+    """X-projection, not 2-D components: a piece that splits vertically (a notch, a highlight) is still one mark."""
+    on = (mask.sum(axis=0) >= _MIN_COLUMN_PIXELS)
+    marks: list = []
+    for x in np.nonzero(on)[0]:
+        x = int(x)
+        if marks and x - marks[-1][1] <= _MARK_GAP_PX:
+            marks[-1][1] = x + 1
+        else:
+            marks.append([x, x + 1])
+    return marks
 
+
+def changed_bbox(
+    before_path: str,
+    after_path: str,
+    exclude: Optional[Sequence[float]] = None,
+) -> Optional[list]:
+    """`exclude` is the handle's own box: left in, the handle and progress bar would dominate the union."""
+    mask = _change_mask(before_path, after_path, exclude)
+    if mask is None:
+        return None
     ys, xs = np.nonzero(mask)
     return [int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1]
+
+
+def locate_piece(
+    before_path: str,
+    after_path: str,
+    travel: float,
+    exclude: Optional[Sequence[float]] = None,
+) -> Optional[dict]:
+    mask = _change_mask(before_path, after_path, exclude)
+    if mask is None:
+        return None
+    marks = _marks(mask)
+    if not marks:
+        return None
+
+    # The piece is the RIGHTMOST mark that is still the same object; searched rather than `marks[-1]` because
+    # a board animating a badge elsewhere puts a mark in the frame that is neither.
+    ghost_w = float(marks[0][1] - marks[0][0])
+    for x1, x2 in reversed(marks[1:]):
+        piece_w = float(x2 - x1)
+        if (piece_w <= _CLEARED_MARK_FRACTION * travel
+                and abs(piece_w - ghost_w) <= max(3.0, _SAME_WIDTH_TOLERANCE * ghost_w)):
+            return {"centre": (x1 + x2) / 2.0, "width": piece_w}
+
+    left, right = float(marks[0][0]), float(marks[-1][1])
+    width = right - left
+    # Too narrow to hold both: one mark only. If it were the piece it began a `travel` to the left, and when that
+    # is off the board it cannot be, so it is the vacated ground and the piece is a travel beyond it.
+    if travel > 0 and width < travel:
+        centre = left + width / 2.0
+        return {"centre": centre + travel if centre - travel < 0 else centre,
+                "width": width}
+    piece_w = width - max(0.0, travel)
+    if piece_w <= 0:
+        return None
+    return {"centre": right - piece_w / 2.0, "width": piece_w}

package/python/src/captchakraken/updater.py

@@ -1,32 +1,3 @@
-"""
-Unified fetch/update for self-hosters.
-
-One command pulls the latest published CaptchaKraken model from the HuggingFace
-org (https://huggingface.co/CaptchaKraken) AND refreshes the local vLLM serving
-stack, so upgrading picks up new model revisions + engine fixes without
-re-running the whole installer:
-
-    captchakraken fetch
-
-What it does (all model-agnostic — repo ids come from `config`, so overriding
-CAPTCHA_LORA_ADAPTER / CAPTCHA_BASE_MODEL retargets it):
-
-  1. Re-downloads the configured captcha LoRA adapter + base model from HF. A
-     no-op when you're already on the latest revision; pulls the new commit
-     otherwise. (Downloads are cached under HF_HOME, same as the installer.)
-  2. Upgrades the vLLM serving stack in the current environment
-     (``pip install -U vllm huggingface_hub``).
-  3. Restarts a locally-managed vLLM server if one is running, so the freshly
-     pulled weights + engine actually take effect. Remote endpoints are left
-     alone (you manage those).
-
-Flags handled by the CLI wrapper:
-  --weights-only   just re-pull weights (skip the pip upgrade)
-  --engine-only    just upgrade vLLM (skip the weight download)
-  --no-restart     don't bounce a running local server
-  --dry-run        print the plan as JSON and do nothing (no network, no pip)
-"""
-
 import os
 import shutil
 import subprocess
@@ -35,17 +6,11 @@ import sys
 from . import config
 
 
-# The vLLM serving stack `fetch` keeps current. Mirrors the `serve` extra in
-# pyproject; upgraded in-place so a self-hoster gets engine fixes without a full
-# reinstall. Kept deliberately small — torch/transformers ride along with vllm.
 ENGINE_PACKAGES = ["vllm", "huggingface_hub"]
 
 
 def _hf_bin() -> "str | None":
-    """Locate the HuggingFace CLI. Prefer the one next to the CURRENT interpreter
-    (the venv the CLI runs in) — the JS driver invokes us via the venv python
-    without its bin dir on PATH — then fall back to PATH. Accepts either the new
-    `hf` entrypoint or the legacy `huggingface-cli`."""
+    """Next to the current interpreter first: the JS driver invokes the venv python without its bin on PATH."""
     here = os.path.dirname(sys.executable)
     for name in ("hf", "huggingface-cli"):
         sibling = os.path.join(here, name)
@@ -55,11 +20,6 @@ def _hf_bin() -> "str | None":
 
 
 def _download_cmd(repo_id: str) -> "list[str]":
-    """The argv that pulls (or refreshes) one HF repo into the local cache. Uses
-    the `hf`/`huggingface-cli` binary when present; otherwise drives
-    `huggingface_hub.snapshot_download` through the current interpreter so a
-    fetch still works from a bare `pip install captchakraken[serve]` (no console
-    script on PATH)."""
     hf = _hf_bin()
     if hf:
         return [hf, "download", repo_id]
@@ -76,24 +36,14 @@ def _pip_upgrade_cmd() -> "list[str]":
 
 
 class LicensedModelError(RuntimeError):
-    """Raised when `fetch` is pointed at weights that are not downloadable."""
+    pass
 
 
 def _refuse_licensed(repo_id: str) -> None:
-    """A licensed model has no Hub repo. Say so, instead of 404ing at the Hub.
-
-    Without this the failure is `RepositoryNotFoundError` from huggingface_hub,
-    which reads as "you are not logged in" or "typo" — so the next thing a
-    self-hoster does is hunt for a token that will never exist. It is also the
-    one place a licensed model's name can plausibly be typed by accident:
-    CAPTCHA_LORA_ADAPTER takes any string and `fetch` hands it straight to the
-    Hub.
-
-    A `private` model is NOT refused here, and that asymmetry is the point.
-    Its repo exists; the 401 an unauthorised puller gets is the true answer,
-    and pre-empting it with a refusal would stop the holder of an authorised
-    token from fetching weights they are entitled to. `_auth_hint` covers the
-    part that IS worth saying in advance.
+    """A licensed model has no Hub repo; the Hub's RepositoryNotFoundError reads as "you are not logged in".
+
+    A `private` model is deliberately NOT refused: its 401 is the true answer, and pre-empting it would stop
+    the holder of an authorised token from fetching weights they are entitled to.
     """
     from . import prompts
 
@@ -111,12 +61,7 @@ def _refuse_licensed(repo_id: str) -> None:
 
 
 def _needs_auth(*repo_ids: "str | None") -> "list[str]":
-    """Which of these repos are registered `availability: private`.
-
-    Reported by `plan()` so `--dry-run` says "this one needs a token" BEFORE
-    the download, rather than leaving a 401 to be read as a typo. Same reason
-    the licensed refusal lives in `plan()` and not at the download call.
-    """
+    """Reported by `plan()` so `--dry-run` says "this needs a token" before the download, not after a 401."""
     from . import prompts
 
     return [r for r in repo_ids if r and prompts.requires_auth(r)]
@@ -130,14 +75,6 @@ def plan(
     base: "str | None" = None,
     lora: "str | None" = None,
 ) -> dict:
-    """Assemble the fetch plan WITHOUT running anything. Pure + side-effect-free
-    so `--dry-run` and the tests can assert exactly what a real run would do.
-
-    Raises `LicensedModelError` rather than planning a download that cannot
-    succeed. Refusing HERE and not at the download call is deliberate: `plan()`
-    is what `--dry-run` prints, so the refusal is visible before anyone runs the
-    real thing, and there is exactly one place to keep it correct.
-    """
     base_model = base or config.base_model()
     lora_adapter = lora or config.lora_adapter()
     base_url = config.base_url()
@@ -162,7 +99,6 @@ def plan(
 
 
 def _is_local(base_url: str) -> bool:
-    # Imported lazily so a plan/dry-run doesn't drag in requests via server_manager.
     from .server_manager import is_local
 
     return is_local(base_url)
@@ -186,11 +122,6 @@ def fetch(
     base: "str | None" = None,
     lora: "str | None" = None,
 ) -> dict:
-    """Pull the latest weights + engine and (optionally) restart a local server.
-
-    Returns a JSON-serializable summary of what was done. On --dry-run, returns
-    the plan with ``"dry_run": true`` and performs no I/O.
-    """
     p = plan(weights=weights, engine=engine, restart=restart, base=base, lora=lora)
     if dry_run:
         return {**p, "dry_run": True}

package/python/src/captchakraken/watcher.py

@@ -1,52 +1,9 @@
-"""
-Auto-solve watcher — the Python mirror of `js/src/watcher.ts`.
-
-Install it once and captchas are solved as they appear, instead of the caller
-having to know where in their script a challenge might show up.
-
-WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
-The obvious implementation is a `MutationObserver` in the page that calls out
-through an exposed binding. That reacts faster, and it is also the one design
-that cannot be made stealthy everywhere: an exposed binding puts a function on
-`window`, and an observer is script the page can enumerate. Under Camoufox both
-are sandboxed and invisible; under vanilla Playwright or patchright they are
-not, and a captcha vendor is precisely the party that looks.
-
-So this injects NOTHING. It drives the same `detect_captcha()` the solver
-already uses, from the driver side, on a timer:
-
-  - nothing is added to the page on ANY launcher, so there is no new detection
-    surface to reason about per platform;
-  - under Camoufox the probe's DOM reads land in its isolated Juggler world for
-    free — that is Camoufox's default for all Playwright evaluation, with
-    `main_world_eval` / an "mw:" prefix as the opt-OUT. This never opts out, so
-    it is isolated there by construction rather than by special-casing;
-  - reaction time is bounded by `interval_ms`, not by the mutation.
-
-ONE WATCHER COVERS THE WHOLE PAGE, FOR ITS WHOLE LIFE
-A page outlives navigation, and so does the watcher holding it: install it once
-and it keeps probing across every `goto`, staying quiet while there is nothing
-to solve and re-arming after each solve. That is deliberately the whole API --
-the case that motivates a browser-wide installer is almost always a challenge
-appearing on request 40 of a run, on the SAME page object the run started with,
-and that is already covered by one line. Pinned in test_browser_compat.py.
-
-WHY IT BLOCKS, WHERE THE TS PORT DOES NOT (CLAUDE.md 1c)
-`solver.watch(page)` in TypeScript returns immediately and watches in the
-background. It cannot here, and the reason is Playwright's, not ours: a SYNC
-Playwright handle is bound to the greenlet that created it, so driving the page
-from a worker thread raises. `threading` would not buy a background watcher, it
-would buy an exception on the first probe.
-
-The two shapes offered instead:
-
-    solver.watch(page).run()          # blocking: hold this page clean
-    watcher = solver.watch(page)
-    while my_own_loop():
-        watcher.poll_once()           # cooperative: you own the cadence
-
-`poll_once()` is the one to reach for inside an existing automation loop; it
-does exactly one probe, solves if there is something to solve, and returns.
+"""Auto-solve watcher, the Python mirror of `js/src/watcher.ts`.
+
+A poll, not an injected MutationObserver: an exposed binding is a function on `window` a captcha vendor can
+enumerate on vanilla Playwright or patchright, so this injects nothing and drives `detect_captcha()` on a timer.
+It blocks where the TS port does not because a sync Playwright handle is bound to the greenlet that created it.
+One watcher covers a page for its whole life, across every `goto` (pinned in test_browser_compat.py).
 """
 
 from __future__ import annotations
@@ -59,12 +16,6 @@ __all__ = ["CaptchaWatcher"]
 
 
 def _page_is_closed(page: Any) -> bool:
-    """True when the launcher says the page is gone.
-
-    Duck-typed like everything else that touches the page: Playwright and
-    Puppeteer both expose `is_closed`/`isClosed`, but this module refuses to
-    depend on either, and a launcher without it is simply treated as open.
-    """
     for name in ("is_closed", "isClosed"):
         probe = getattr(page, name, None)
         if callable(probe):
@@ -76,38 +27,26 @@ def _page_is_closed(page: Any) -> bool:
 
 
 def _report(callback: Optional[Callable[[Any], Any]], value: Any) -> None:
-    """Hand a value to a user callback without letting its failure reach the loop."""
     if callback is None:
         return
     try:
         callback(value)
     except Exception:
-        # A throwing callback is the caller's bug, not a reason to stop watching.
         pass
 
 
 @dataclass
 class CaptchaWatcher:
-    """Polls one page and solves whatever captcha becomes visible on it."""
 
     solver: Any
     page: Any
-    #: Milliseconds between probes. Each tick costs one `detect_captcha()` — a
-    #: handful of selector queries. Below ~250ms you pay real CPU for latency
-    #: the solve itself (seconds) makes irrelevant.
+    # Below ~250ms is real CPU for latency the solve itself (seconds) makes irrelevant.
     interval_ms: int = 1000
-    #: Stop after this many successful solves. None means unlimited.
     max_solves: Optional[int] = None
-    #: Wait this long after a solve RAISES before probing again. Without it a
-    #: permanently unsupported challenge — an invisible reCAPTCHA v3, say —
-    #: becomes a hot loop that re-attempts and re-bills every interval forever.
+    # Without it a permanently unsupported challenge (an invisible reCAPTCHA v3) re-attempts and re-bills forever.
     error_backoff_ms: int = 5000
-    #: Called with the `SolveResult` of each completed solve.
     on_solved: Optional[Callable[[Any], Any]] = None
-    #: Called with any exception from detection or solving. Errors are reported,
-    #: never fatal: `NoCaptchaFoundError` fires routinely when a widget vanishes
-    #: between the probe and the solve, and a watcher that died on it would be
-    #: useless.
+    # Never fatal: NoCaptchaFoundError fires routinely when a widget vanishes between the probe and the solve.
     on_error: Optional[Callable[[BaseException], Any]] = None
 
     solves: int = field(default=0, init=False)
@@ -115,46 +54,26 @@ class CaptchaWatcher:
 
     @property
     def running(self) -> bool:
-        """False once stopped, the page closed, or `max_solves` was reached."""
         if self._stopped or _page_is_closed(self.page):
             return False
         return self.max_solves is None or self.solves < self.max_solves
 
     def stop(self) -> None:
-        """End the loop. Safe to call from `on_solved` / `on_error`, or twice."""
         self._stopped = True
 
     def poll_once(self) -> Optional[Any]:
-        """
-        One probe. Solves if a captcha is visible; returns its `SolveResult`,
-        or None when there was nothing to do (or the attempt failed and was
-        reported to `on_error`).
-
-        Does NOT sleep — the caller owns the cadence. `run()` is this plus the
-        waiting and the backoff.
-        """
         return self._attempt()[0]
 
     def _attempt(self) -> Tuple[Optional[Any], bool]:
-        """
-        `(result, failed)`.
-
-        The second element is the whole reason this is not just `poll_once`:
-        that method returns None both for "no captcha on the page" and for "a
-        solve was attempted and raised", and `run()` must back off after the
-        second while re-probing cheaply after the first. Collapsing the two
-        either hot-loops on an unsupported challenge or adds a five-second
-        stall to every idle tick.
-        """
+        """`(result, failed)`: `poll_once` conflates "nothing" and "raised", and only the latter backs off."""
         if not self.running:
             return None, False
+        # KeyboardInterrupt / SystemExit are deliberately not caught: Ctrl-C during a solve must reach the caller.
         try:
             if not self.solver.detect_captcha(self.page):
                 return None, False
             result = self.solver.solve(self.page)
-        except Exception as exc:  # noqa: BLE001 - reported, never fatal
-            # KeyboardInterrupt / SystemExit are deliberately NOT caught: a
-            # Ctrl-C during a long solve must reach the caller.
+        except Exception as exc:
             if _page_is_closed(self.page):
                 self.stop()
                 return None, False
@@ -166,7 +85,6 @@ class CaptchaWatcher:
         return result, False
 
     def _sleep(self, ms: float) -> None:
-        """Sleep in slices so `stop()` and Ctrl-C are not held for a whole interval."""
         deadline = time.monotonic() + ms / 1000.0
         while time.monotonic() < deadline:
             if self._stopped:
@@ -174,13 +92,6 @@ class CaptchaWatcher:
             time.sleep(min(0.1, max(0.0, deadline - time.monotonic())))
 
     def run(self, timeout_ms: Optional[int] = None) -> int:
-        """
-        Watch until `stop()`, the page closes, `max_solves` is hit, or
-        `timeout_ms` elapses. Returns the number of captchas solved.
-
-        Blocking by design — see this module's docstring on why the TypeScript
-        port can hand back a background handle and this cannot.
-        """
         deadline = None if timeout_ms is None else time.monotonic() + timeout_ms / 1000.0
         while self.running:
             if deadline is not None and time.monotonic() >= deadline:

package/scripts/copy-python.mjs

@@ -1,11 +1,3 @@
-// Bundle the sibling `../python` (the `captchakraken` package) into `./python`
-// so the published npm package is self-contained: the JS solver shells out to
-// this bundled engine for OpenCV grid detection and the vLLM planner.
-//
-// npm can only pack files inside the package root, so the single source of truth
-// at repo-root `python/` is copied in here at build time. Runtime source (src/)
-// + pyproject are what the postinstall `pip install .` needs; tests, caches,
-// venvs and build artifacts are skipped.
 import { cpSync, rmSync, existsSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -19,11 +11,19 @@ if (!existsSync(src)) {
   process.exit(1)
 }
 
-const SKIP = new Set(['.venv', '__pycache__', 'dist', 'build', '.pytest_cache', '.ruff_cache', 'tests'])
+const SKIP = new Set([
+  '.venv', '__pycache__', 'dist', 'build', '.pytest_cache', '.ruff_cache', 'tests',
+  'coverage', 'htmlcov', '.nyc_output', 'coverage.xml', 'lcov.info',
+
+  'latestDebugRun',
+])
 
 rmSync(dest, { recursive: true, force: true })
 cpSync(src, dest, {
   recursive: true,
-  filter: (p) => !p.split(/[\\/]/).some((seg) => SKIP.has(seg) || seg.endsWith('.egg-info')),
+  filter: (p) =>
+    !p
+      .split(/[\\/]/)
+      .some((seg) => SKIP.has(seg) || seg.endsWith('.egg-info') || seg.startsWith('.coverage')),
 })
 console.log('[copy-python] bundled python/ engine -> js/python/')

package/scripts/setup-python.js

@@ -1,13 +1,3 @@
-/**
- * postinstall bootstrap: create a local venv under `python/.venv` and install the
- * bundled `captchakraken` package so `python -m captchakraken.cli` works out-of-the-box.
- *
- * Opt out:
- *   CAPTCHA_KRAKEN_SKIP_PYTHON_SETUP=1
- *
- * Force a specific system python:
- *   CAPTCHA_KRAKEN_PYTHON=/path/to/python3
- */
 const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
@@ -42,7 +32,7 @@ function venvPython(venvDir) {
 
 function resolveSystemPython() {
   if (process.env.CAPTCHA_KRAKEN_PYTHON) return process.env.CAPTCHA_KRAKEN_PYTHON;
-  // Try python3 first, then python.
+
   return process.platform === 'win32' ? 'python' : 'python3';
 }
 
@@ -76,15 +66,6 @@ function main() {
     run(py, ['-m', 'pip', 'install', '--upgrade', 'pip', 'setuptools', 'wheel'], { cwd: cliRoot });
   }
 
-  // Install the `captchakraken` package with its CORE (lightweight) deps only:
-  // OpenCV grid detection + the HTTP planner that talks to a vLLM server. The
-  // heavy serving stack (vllm/torch, the `[serve]` extra) is NOT installed here
-  // — that's what setup.sh installs for people self-hosting the model.
-  //
-  // Prefer the PUBLISHED package from PyPI, pinned to THIS npm package's version
-  // so the JS driver and the Python engine stay in lockstep. Only fall back to
-  // the bundled source tree when PyPI can't satisfy that pin — offline installs,
-  // or a dev/CI/from-git build whose version isn't on PyPI yet.
   const pkgVersion = require(path.join(pkgRoot, 'package.json')).version;
   try {
     console.log(`[CaptchaKraken] Installing captchakraken==${pkgVersion} from PyPI...`);
@@ -115,4 +96,3 @@ try {
   if (strict) process.exit(1);
 }
 
-

package/dist/trajectory.d.ts

@@ -1,58 +0,0 @@
-/**
- * Human-like mouse trajectories for the page driver.
- *
- * The TypeScript side of `python/src/captchakraken/trajectory.py`; the two are
- * one implementation in two languages, pinned by `test_trajectory_parity.py`.
- *
- * What makes the output human rather than a lerp:
- *   - a Bezier arc, not a straight line (hand motion bows)
- *   - Fitts's-law duration: distance and precision set the time, not a constant
- *   - an ease-in-out velocity profile, so the cursor accelerates then brakes
- *   - sub-pixel jitter that scales with speed (fast motion is sloppier)
- *   - a small overshoot-and-correct on longer moves, which is the single most
- *     recognisable human tell and the one a linear interpolation never produces
- *
- * `generate_swipe` is the SAME contract for a FINGER, and it is a different
- * model rather than the mouse model with different constants — see its
- * docstring.
- *
- * Camoufox's own `humanize` is a DIFFERENT, browser-level mechanism that
- * re-humanises every `mouse.move()` it is handed. Running both composes them —
- * measured 82.1s vs 13.4s on one a GeeTest v4 slider solve, because each of the 60
- * points below became its own humanised sub-trajectory. Drive with humanize off.
- */
-export type Point = [number, number];
-/**
- * Returns `[points, timings]`. `timings` is CUMULATIVE milliseconds from the
- * gesture start — not per-step deltas — because that is what `tracePath` sleeps
- * against, and both drivers must pace identically.
- *
- * `frequency` is samples per second (the driver passes 60).
- * `frequencyRandomizer` jitters each frame's timestamp so the sample interval
- * is not a metronome; a perfectly periodic mousemove stream is trivially
- * detectable.
- */
-export declare function generate_trajectory(target_start: readonly number[], target_end: readonly number[], frequency?: number, frequencyRandomizer?: number): [Point[], number[]];
-/**
- * A FINGER travelling from `target_start` to `target_end`, same contract as
- * `generate_trajectory`: `[points, timings]`, timings cumulative from 0, last
- * point exactly `target_end`.
- *
- * A separate model rather than `generate_trajectory` with other constants,
- * because the three things that make the mouse output human are each WRONG
- * here:
- *
- *   - **No overshoot-and-correct.** That tell is a hand arriving past a target
- *     it cannot see under the cursor. A finger occludes its own target and
- *     commits; the correction, when there is one, is a second gesture.
- *   - **A different velocity profile.** `easeTouch`, not `easeInOut` — above.
- *   - **Different jitter.** The mouse model adds white noise scaled by speed (a
- *     hand tracking a path imprecisely). A digitizer instead reports a wandering
- *     centroid, which is low-frequency and roughly speed INDEPENDENT, so this is
- *     a smoothed random walk.
- *
- * `frequency` defaults to 90: digitizers sample at 120Hz+, but touchmove is
- * coalesced to the compositor, so more samples than this buys nothing and costs
- * a dispatch round-trip each.
- */
-export declare function generate_swipe(target_start: readonly number[], target_end: readonly number[], frequency?: number, frequencyRandomizer?: number): [Point[], number[]];