captchakraken 3.2.0 → 4.0.0

package/python/src/captchakraken/captchakraken.config.json

@@ -0,0 +1,416 @@
+{
+  "_comment": [
+    "Every URL pattern and selector the solver detects and drives a captcha with.",
+    "",
+    "This file is the default: PageSolver (Python) and CaptchaKraken (JS) load it",
+    "when no other is given. To add your own, write a file of the same shape and",
+    "pass its path (or the parsed object) as `selectors` in PageSolverConfig",
+    "(Python) or CaptchaKrakenConfig (JS). A file of your own may hold only what",
+    "it changes: `custom`, any vendor under `vendors` (it replaces that vendor's",
+    "whole entry), or any list under `generic`; the rest comes from this file.",
+    "",
+    "custom: your own entry, for a captcha the built-in vendors do not know. It",
+    "is detected before every built-in vendor and reported as `unknown`, and its",
+    "submit, text box, refresh and slider controls are tried before the generic",
+    "ones. It must name a `widget`, `challenge` or `checkbox`; `hosts` is optional.",
+    "",
+    "detector: the element detector that finds grids, tick boxes and pieces on the",
+    "CPU before any model is asked. `standard` (ResNet-18, 124 MB), `lite`",
+    "(MobileNetV3, 24 MB, ~6x faster on one CPU) or `auto`: lite on two usable",
+    "CPUs or fewer, and above that standard only when a one-off timing predicts",
+    "it inside 200 ms a board. Only the chosen model is downloaded.",
+    "CAPTCHA_KRAKEN_DETECTOR_MODEL overrides this.",
+    "",
+    "vendors: one entry per vendor, in detection order. Order matters: the driver",
+    "takes the first visible match in table order. `hosts` are URL substrings of",
+    "the vendor's code on the wire; every other field is a list of CSS (or",
+    "Playwright `xpath=`) selectors, except `response`, `checked`, `accepted` and",
+    "`fresh` (one selector each), `banners` ([selector, verdict] pairs) and",
+    "`hold_completes` (true or false). `note` is for people, not the solver.",
+    "",
+    "generic: the fallbacks tried after every vendor's own. `submit_text` is the",
+    "button text probed for a submit control, in order.",
+    "",
+    "Keys starting with `_` are comments. Field reference: `_fields`."
+  ],
+  "_fields": {
+    "hosts": "URL substrings of the vendor's code on the wire. A tripwire, not a detector: the host stays on the wire when a vendor renames its markup (see TRIBAL_KNOWLEDGE.md). BotDetect is self-hosted, so it has none.",
+    "challenge": "On the host page: the open challenge. Detected first.",
+    "checkbox": "On the host page: the checkbox. Detected while `response` is empty and `checked` is not showing.",
+    "enclave": "On the host page: a frame the vendor draws its other frames inside. Every host-page selector also reads the inside of a visible one.",
+    "widget": "On the host page: inline widget shapes, detected last. Iframe selectors go first; a class that lives inside the frame document (.CheckboxCaptcha, .mtcap) only ever matches an inline embed.",
+    "response": "On the host page: the field the vendor fills on success. Read first and unconditionally, because hCaptcha's overlay hides the anchor.",
+    "checked": "Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`.",
+    "box": "Inside the checkbox frame: the box itself, clicked from the DOM. A vendor without one is found on a photograph. An in-page checkbox that names one is a button with no tick box to find, and is clicked where it is.",
+    "accepted": "On the host page: the vendor painted its success state. Visibility is part of the test (see TRIBAL_KNOWLEDGE.md).",
+    "fresh": "Inside the challenge frame: a new round has painted, with text.",
+    "images": "Inside the challenge frame: the pictures a board is made of; the driver waits for each to have painted.",
+    "submit": "Inside the widget: the vendor's own submit control, tried after the generic text probes.",
+    "banners": "Inside the challenge frame: verdict banners and what each means.",
+    "blocked": "Inside the challenge frame: the vendor refusing to serve this client at all. Nothing after it can succeed.",
+    "passive": "On the host page: the vendor's frames that are never interactive, so a page showing only these has no widget.",
+    "text_input": "Inside the widget, and its enclosing fieldset/form: the answer box of a typed captcha.",
+    "slider_handle": "Inside the widget: the knob a slide must start on; a drag from the piece moves nothing.",
+    "piece": "Inside the widget: the piece, measured to steer the slide and dragged directly when there is no track.",
+    "refresh": "Inside the widget: the control that deals a new puzzle, pressed when the model answers `refresh`.",
+    "hold_completes": "A press-and-hold that completes on its own once full, and resets when let go before it has: the fill reaching the answer's `to` is not a release, and the hold lasts until the widget says it is done."
+  },
+  "detector": "auto",
+  "custom": null,
+  "vendors": {
+    "recaptcha": {
+      "note": "An Enterprise sitekey serves the same widget from /recaptcha/enterprise/ instead of /recaptcha/api2/.",
+      "hosts": [
+        "google.com/recaptcha",
+        "recaptcha.net"
+      ],
+      "challenge": [
+        "iframe[src*=\"recaptcha/api2/bframe\"]",
+        "iframe[src*=\"recaptcha/enterprise/bframe\"]"
+      ],
+      "checkbox": [
+        "iframe[src*=\"recaptcha/api2/anchor\"]:not([src*=\"size=invisible\"])",
+        "iframe[src*=\"recaptcha/enterprise/anchor\"]:not([src*=\"size=invisible\"])"
+      ],
+      "response": "[name=\"g-recaptcha-response\"]",
+      "checked": ".recaptcha-checkbox-checked",
+      "box": [
+        "#recaptcha-anchor"
+      ],
+      "fresh": ".rc-imageselect-instructions, #rc-imageselect",
+      "submit": [
+        "#recaptcha-verify-button"
+      ],
+      "banners": [
+        [
+          ".rc-imageselect-error-select-more",
+          "select-more"
+        ],
+        [
+          ".rc-imageselect-error-dynamic-more",
+          "dynamic-more"
+        ],
+        [
+          ".rc-imageselect-incorrect-response",
+          "rejected"
+        ]
+      ],
+      "blocked": [
+        ".rc-doscaptcha-header-text"
+      ],
+      "passive": [
+        "iframe[src*=\"size=invisible\"]"
+      ],
+      "refresh": [
+        "#recaptcha-reload-button"
+      ]
+    },
+    "hcaptcha": {
+      "note": "Keyed on the `hcaptcha` substring, not the apex host: challenges are served off newassets.hcaptcha.com. secure-api.js draws every frame inside a full-viewport enclave, one per render, and only a visible one holds an open challenge.",
+      "hosts": [
+        "hcaptcha.com"
+      ],
+      "challenge": [
+        "iframe[src*=\"hcaptcha\"][src*=\"frame=challenge\"]"
+      ],
+      "checkbox": [
+        "iframe[src*=\"hcaptcha\"][src*=\"frame=checkbox\"]:not([src*=\"frame=checkbox-invisible\"])"
+      ],
+      "enclave": [
+        "iframe[src*=\"hcaptcha\"][src*=\"frame=enclave\"]"
+      ],
+      "response": "[name=\"h-captcha-response\"]",
+      "checked": "#checkbox[aria-checked=\"true\"]",
+      "box": [
+        "#checkbox"
+      ],
+      "fresh": ".prompt-text",
+      "images": [
+        ".task-image .image",
+        ".task .image",
+        ".challenge-example img",
+        ".image-wrapper img"
+      ],
+      "submit": [
+        ".button-submit"
+      ],
+      "passive": [
+        "iframe[src*=\"hcaptcha\"][src*=\"frame=enclave\"]",
+        "iframe[src*=\"hcaptcha\"][src*=\"frame=checkbox-invisible\"]"
+      ],
+      "refresh": [
+        ".refresh.button"
+      ]
+    },
+    "turnstile": {
+      "hosts": [
+        "challenges.cloudflare.com"
+      ],
+      "checkbox": [
+        "iframe[src*=\"challenges.cloudflare.com\"]",
+        ".cf-turnstile"
+      ],
+      "response": "[name=\"cf-turnstile-response\"]"
+    },
+    "geetest": {
+      "note": "v4's \"Click to verify\" bar opens the puzzle. Its container wears `geetest_freeze_wait` while the puzzle is open (`geetest_boxShow` only until a first wrong answer, after which the box stays up dealing a new one) and `geetest_success` once passed, so the checkbox matches only a bar that has not been clicked yet.",
+      "hosts": [
+        "geetest.com"
+      ],
+      "checkbox": [
+        ".geetest_captcha:not(.geetest_boxShow):not(.geetest_freeze_wait):not(.geetest_success):not(.geetest_lock_success) .geetest_btn_click"
+      ],
+      "widget": [
+        ".geetest_box",
+        ".geetest_panel_box",
+        ".geetest_popup_window",
+        ".geetest_widget"
+      ],
+      "box": [
+        ".geetest_btn_click"
+      ],
+      "accepted": ".geetest_result_tips.geetest_success, .geetest_captcha.geetest_success, .geetest_captcha.geetest_lock_success",
+      "submit": [
+        ".geetest_submit"
+      ],
+      "slider_handle": [
+        ".geetest_slider_button",
+        ".geetest_btn",
+        ".geetest_slider .geetest_arrow"
+      ],
+      "piece": [
+        ".geetest_slice"
+      ],
+      "refresh": [
+        ".geetest_refresh",
+        ".geetest_refresh_1"
+      ]
+    },
+    "tencent": {
+      "note": "Both in-page and iframe shapes stay (Tencent moved in-host on 2026-08-11; see TRIBAL_KNOWLEDGE.md), and the iframe id is prefix-anchored: `[id*=tcaptcha]` also matched MTCaptcha's iframe and hid that `.mtcap` matched nothing.",
+      "hosts": [
+        "captcha.gtimg.com",
+        "captcha.qcloud.com"
+      ],
+      "widget": [
+        "#tcaptcha_transform_dy",
+        "#tCaptchaDyContent",
+        ".tencent-captcha-dy__content",
+        "iframe#tcaptcha_iframe_dy",
+        "iframe[id^=\"tcaptcha\"]",
+        "iframe[src*=\"captcha.gtimg.com\"]",
+        "iframe[src*=\"captcha.qq.com\"]"
+      ],
+      "slider_handle": [
+        ".tencent-captcha-dy__slider-block",
+        "#tcaptcha_drag_thumb",
+        ".tc-slider-normal",
+        "[id*=slideBlock]"
+      ],
+      "piece": [
+        ".tencent-captcha-dy__fg-item"
+      ],
+      "refresh": [
+        ".tencent-captcha-dy__footer-icon--refresh"
+      ]
+    },
+    "yidun": {
+      "hosts": [
+        "dun.163.com",
+        "cstaticdun.126.net",
+        "necaptcha.nosdn.127.net"
+      ],
+      "widget": [
+        ".yidun_panel",
+        ".yidun"
+      ],
+      "slider_handle": [
+        ".yidun_slider",
+        ".yidun_jigsaw"
+      ],
+      "piece": [
+        ".yidun_jigsaw"
+      ],
+      "refresh": [
+        ".yidun_refresh"
+      ]
+    },
+    "yandex": {
+      "hosts": [
+        "smartcaptcha.yandexcloud.net"
+      ],
+      "widget": [
+        "iframe[src*=\"smartcaptcha.yandexcloud.net/advanced\"]",
+        "iframe[src*=\"smartcaptcha.yandexcloud.net\"]",
+        ".CheckboxCaptcha"
+      ],
+      "text_input": [
+        ".AdvancedCaptcha-Input input",
+        "input.Textinput-Control",
+        "input[name=\"rep\"]"
+      ]
+    },
+    "lemin": {
+      "hosts": [
+        "leminnow.com"
+      ],
+      "widget": [
+        "#lemin-cropped-captcha",
+        ".lemin-captcha-popup"
+      ],
+      "slider_handle": [
+        ".lemin-slider-handle",
+        "#lemin-cropped-captcha .slider"
+      ],
+      "piece": [
+        ".lemin-cropped-puzzle-piece",
+        "#lemin-cropped-captcha canvas + canvas"
+      ]
+    },
+    "prosopo": {
+      "hosts": [
+        "prosopo.io"
+      ],
+      "widget": [
+        ".prosopo-modalInner",
+        ".procaptcha-checkbox"
+      ]
+    },
+    "mtcaptcha": {
+      "hosts": [
+        "mtcaptcha.com"
+      ],
+      "widget": [
+        "iframe[src*=\"service.mtcaptcha.com\"]",
+        "iframe[id^=\"mtcaptcha-iframe\"]",
+        ".mtcaptcha",
+        ".mtcap"
+      ],
+      "text_input": [
+        "input.mtcap-inputtext",
+        ".mtcap input[type=text]"
+      ],
+      "refresh": [
+        ".mtcap-refresh"
+      ]
+    },
+    "botdetect": {
+      "hosts": [],
+      "widget": [
+        ".BDC_CaptchaDiv"
+      ],
+      "text_input": [
+        "input[id*=captchaCode]",
+        "input#captchaCode",
+        "input[id*=validateCaptcha]",
+        ".BDC_CaptchaDiv input[type=text]"
+      ],
+      "refresh": [
+        "a[id*=\"ReloadLink\"]",
+        ".BDC_ReloadIcon"
+      ]
+    },
+    "human": {
+      "note": "The press-and-hold widget. Found by its host-page container whether the button is drawn inline or in the vendor's iframe inside it: the hold is performed on a photograph of the container, so it never needs the frame's DOM.",
+      "hosts": [],
+      "widget": [
+        "#px-captcha"
+      ],
+      "hold_completes": true
+    },
+    "awswaf": {
+      "note": "The card is drawn in an open shadow root, which the locator engine pierces; its Confirm is found by the text probe.",
+      "hosts": [
+        "awswaf.com"
+      ],
+      "widget": [
+        ".amzn-captcha-modal"
+      ]
+    },
+    "captchafox": {
+      "note": "The puzzle opens in a modal over the \"I am human\" box, which stays on screen, so the modal is a challenge: a widget would be outranked by the box and the box clicked again.",
+      "hosts": [
+        "captchafox.com"
+      ],
+      "challenge": [
+        ".cf-modal__challenge"
+      ],
+      "checkbox": [
+        "div[id^=\"cf-widget-\"]"
+      ],
+      "response": "[name=\"cf-captcha-response\"]",
+      "slider_handle": [
+        ".cf-slider__button"
+      ]
+    },
+    "dingxiang": {
+      "note": "Every mode opens the same popup card. The trigger bar under it has no box to tick and is not a widget.",
+      "hosts": [
+        "cdn.dingxiang-inc.com/ctu-group/captcha",
+        "cap.dingxiang-inc.com"
+      ],
+      "widget": [
+        ".dx_captcha_oneclick_one-step"
+      ],
+      "slider_handle": [
+        ".dx_captcha_basic_slider",
+        ".dx_captcha_rotate_slider"
+      ]
+    },
+    "funcaptcha": {
+      "note": "The host page carries the outer frame (iframe.arkoselabs.com/<key>/index.html) and the game is two frames inside it; the game frame's own path is listed so a page that frames the game directly is found too.",
+      "hosts": [
+        "arkoselabs.com"
+      ],
+      "widget": [
+        "iframe[src*=\"arkoselabs.com\"]",
+        "iframe[src*=\"ec-game-core/game-core\"]"
+      ],
+      "hold_completes": true
+    },
+    "proton": {
+      "note": "Proton frames its own captcha at /core/v4/captcha, on account-api.proton.me or under the app's own /api/.",
+      "hosts": [
+        "/core/v4/captcha"
+      ],
+      "widget": [
+        "iframe[src*=\"/core/v4/captcha\"]"
+      ]
+    },
+    "unknown": {
+      "hosts": []
+    }
+  },
+  "generic": {
+    "submit_text": [
+      "verify",
+      "next",
+      "submit",
+      "skip",
+      "confirm"
+    ],
+    "text_input": [
+      "input[name*=\"captcha\" i]",
+      "input[id*=\"captcha\" i]",
+      "input[aria-label*=\"captcha\" i]",
+      "input[placeholder*=\"code\" i]",
+      "input[autocomplete=\"off\"][type=text]",
+      "input[type=text]",
+      "input:not([type])",
+      "input[type=tel]",
+      "textarea"
+    ],
+    "slider_handle": [
+      "[role=\"slider\"]",
+      "[aria-valuenow]",
+      "[class*=\"slider\"][class*=\"btn\"]",
+      "[class*=\"slider\"][class*=\"button\"]",
+      "[class*=\"slide\"][class*=\"handle\"]",
+      "[class*=\"drag\"][class*=\"thumb\"]"
+    ],
+    "piece": [
+      "[class*=\"puzzle\"][class*=\"piece\"]",
+      "[class*=\"jigsaw\"]"
+    ]
+  }
+}

package/python/src/captchakraken/cli.py

@@ -1,4 +1,4 @@
-"""The `captchakraken` CLI: one-shot solves, the OpenCV tool calls, the CV worker, and server management.
+"""The `captchakraken` CLI: one-shot solves, the detector tool calls, the CV worker, and server management.
 
 `captchakraken image.png [model] [api_provider] [api_key] [--puzzle-source ...]` solves one still.
 Exit codes: 1 failure, 2 unsupported puzzle, 3 the hosted API refused.
@@ -16,7 +16,6 @@ from .errors import CaptchaKrakenAPIError
 from .kinds import Outcome, PromptFamily, RetryMode, Vendor
 from .solver import CaptchaSolver, UnsupportedCaptchaError
 
-
 _SELF_PRINTED = object()
 
 
@@ -59,12 +58,10 @@ def match_region(ref: str, live: str, cx: float, cy: float, tolerance: Optional[
 
     The neighbourhood only: a whole-frame match would need every unrelated sprite to align and would essentially never open.
     """
-    import cv2
-
-    from .keyframes import MATCH_REGION_TOLERANCE, region_box, region_diff_ratio
+    from .keyframes import MATCH_REGION_TOLERANCE, read_frame, region_box, region_diff_ratio
 
     tol = MATCH_REGION_TOLERANCE if tolerance is None else float(tolerance)
-    a, b = cv2.imread(ref), cv2.imread(live)
+    a, b = read_frame(ref), read_frame(live)
     if a is None or b is None:
         return {"match": False, "diff": 1.0, "error": "unreadable image"}
     d = region_diff_ratio(a, b, region_box(a.shape[1::-1], (cx, cy)))
@@ -77,12 +74,36 @@ def board_painted(image: str, floor=None, box=None) -> dict:
     return board_is_painted(image, floor, box)
 
 
-def track_piece(before: str, after: str, exclude=None, travel: float = 0.0) -> dict:
-    from .tool_calls.track_piece import changed_bbox, locate_piece
+def slide_step(req: dict) -> dict:
+    """One look of the slide loop (`tool_calls/slide_tracker.py`); a lost or unseen object is `{"error"}`, never a
+    position, so the driver releases rather than steering by a guess."""
+    from .tool_calls.slide_tracker import TrackingError
+    from .tool_calls.slide_tracker import slide_step as step
+
+    def pt(v):
+        return None if v is None else (float(v[0]), float(v[1]))
+
+    try:
+        return step(req["first"], req["probe"], req["current"], probe_s=req["probe_s"], s=req["s"],
+                    goal=pt(req["goal"]), seed=pt(req.get("seed")), handle=pt(req.get("handle")),
+                    bounds=tuple(req["bounds"]) if req.get("bounds") else None,
+                    history=req.get("history") or (), tol=float(req.get("tol") or 2.0))
+    except TrackingError as e:
+        return {"error": str(e)}
 
-    bbox = changed_bbox(before, after, exclude)
-    piece = locate_piece(before, after, travel, exclude) if bbox is not None else None
-    return {"bbox": bbox, "piece": piece, "moved": bbox is not None}
+
+def fill_step(req: dict) -> dict:
+    """One look at a held widget's fill (`tool_calls/fill_tracker.py`); an unreadable line is `{"error"}`, never a
+    release, so the driver keeps holding on the widget's own signals."""
+    from .tool_calls.fill_tracker import FillError
+    from .tool_calls.fill_tracker import fill_step as step
+
+    try:
+        return step(req["first"], req["current"], start=tuple(req["start"]), end=tuple(req["end"]), t=float(req["t"]),
+                    history=req.get("history") or (), poll_s=float(req.get("poll_s") or 0.25),
+                    tol=float(req.get("tol") or 2.0), first_t=req.get("first_t"))
+    except FillError as e:
+        return {"error": str(e)}
 
 
 def _find_grid(args):
@@ -164,10 +185,16 @@ def _board_painted(args):
     return board_painted(args[0], float(args[1]) if len(args) > 1 else None)
 
 
-def _track_piece(args):
-    _need(args, 2, "track-piece before.png after.png [exclude_json] [travel]")
-    return track_piece(args[0], args[1], json.loads(args[2]) if len(args) > 2 else None,
-                       float(args[3]) if len(args) > 3 else 0.0)
+def _slide_step(args):
+    _need(args, 1, "slide-step request.json  (or the JSON itself)")
+    raw = args[0]
+    return slide_step(json.loads(open(raw).read() if os.path.exists(raw) else raw))
+
+
+def _fill_step(args):
+    _need(args, 1, "fill-step request.json  (or the JSON itself)")
+    raw = args[0]
+    return fill_step(json.loads(open(raw).read() if os.path.exists(raw) else raw))
 
 
 def _report_outcome(args):
@@ -212,8 +239,10 @@ def _serve(args):
             return board_painted(req["image"], req.get("floor"), req.get("box"))
         if cmd == "find-checkbox":
             return find_checkbox(req["image"])
-        if cmd == "track-piece":
-            return track_piece(req["before"], req["after"], req.get("exclude"), req.get("travel") or 0.0)
+        if cmd == "slide-step":
+            return slide_step(req)
+        if cmd == "fill-step":
+            return fill_step(req)
         raise ValueError(f"unknown cmd: {cmd!r}")
 
     sys.stdout.write(json.dumps({"ready": True}) + "\n")
@@ -249,7 +278,7 @@ def _run_solve(query: Callable[[], dict]) -> None:
 
 
 def _solve_animated(args):
-    """Slice a recorded burst (zero-padded PNGs in `--frames-dir`) into keyframes and solve them."""
+    """Solve a recorded burst (zero-padded PNGs in `--frames-dir`) as the model's prompt generation asks it."""
     import glob
 
     parser = argparse.ArgumentParser(prog="captchakraken solve-animated")
@@ -264,20 +293,21 @@ def _solve_animated(args):
         _fail(f"no frames in {opts.frames_dir}")
 
     def query():
-        import cv2
-
-        from .keyframes import extract_keyframes, write_keyframes
+        from .keyframes import read_frame
+        from .solver import cut_recording
 
-        imgs = [im for im in (cv2.imread(p) for p in frames) if im is not None]
+        imgs = [im for im in (read_frame(p) for p in frames) if im is not None]
         if not imgs:
             _fail("no frame decoded")
-        kfset = extract_keyframes(imgs, fps=float(opts.fps))
-        paths = [os.path.abspath(p) for p in write_keyframes(kfset, os.path.join(opts.frames_dir, "keyframes"), stem="challenge")]
+        recording = cut_recording(imgs, float(opts.fps), os.path.abspath(os.path.join(opts.frames_dir, "keyframes")))
         solver = CaptchaSolver(model=opts.model, api_key=opts.api_key, expert=opts.expert)
-        result = solver.solve_keyframes(paths)
-        return {"actions": [a.model_dump() for a in result], "token_usage": solver.planner.token_usage,
-                "keyframes": paths, "keyframe_mode": kfset.mode, "steady_screens": kfset.steady_screens,
-                "source_frames": len(imgs)}
+        result = solver.solve_animated(recording)
+        kfset = recording.keyframes
+        return {"actions": [a.model_dump() for a in result],
+                "fallbacks": [[a.model_dump() for a in plan] for plan in solver.pointer_fallback_actions()],
+                "token_usage": solver.planner.token_usage,
+                "keyframes": recording.keyframe_paths, "keyframe_mode": kfset.mode,
+                "steady_screens": kfset.steady_screens, "source_frames": len(imgs)}
 
     _run_solve(query)
     return _SELF_PRINTED
@@ -332,7 +362,8 @@ COMMANDS: Dict[str, Callable[[List[str]], Any]] = {
     "grid-cell-states-fixed": _grid_cell_states_fixed,
     "match-region": _match_region,
     "board-painted": _board_painted,
-    "track-piece": _track_piece,
+    "slide-step": _slide_step,
+    "fill-step": _fill_step,
     "report-outcome": _report_outcome,
     "serve": _serve,
     "solve-animated": _solve_animated,
@@ -371,15 +402,20 @@ def main():
                         help="Force one expert of a routed model. Also CAPTCHA_EXPERT.")
     parser.add_argument("--text-mode", action="store_true",
                         help="The widget has a text box, so the answer is typed rather than clicked.")
+    parser.add_argument("--history", action="append", default=[],
+                        help="An earlier screen of the same paged puzzle, oldest first (repeatable).")
     args = parser.parse_args()
     _image(args.image_path)
 
     def query():
         solver = CaptchaSolver(model=args.model, api_key=args.api_key, expert=args.expert)
+        solver.planner.pointer_history = list(args.history)
         result = solver.solve(args.image_path, puzzle_source=args.puzzle_source,
                               retry_mode=args.retry_mode, text_mode=args.text_mode)
         actions = [a.model_dump() for a in result] if isinstance(result, list) else result.model_dump()
-        return {"actions": actions, "token_usage": solver.planner.token_usage}
+        return {"actions": actions,
+                "fallbacks": [[a.model_dump() for a in plan] for plan in solver.pointer_fallback_actions()],
+                "token_usage": solver.planner.token_usage}
 
     _run_solve(query)