captchakraken 3.2.0 → 4.0.0

package/python/src/captchakraken/prompts.py

@@ -15,6 +15,10 @@ _DISABLE_FETCH_ENV = "CAPTCHA_PROMPTS_NO_FETCH"
 
 LATEST_PROMPT_VERSION = "2"
 
+# The generations that show the model an animated captcha as one video (`clipvideo.py`) and read the moment it
+# acts on as `"t"`, in seconds. Every earlier generation sends numbered keyframe stills and reads `"frame"`.
+VIDEO_GENERATIONS = ("3", "4")
+
 
 # Pure literals only, no f-strings, joins or constant references: the training repo's release parity gate reads
 # this dict by AST without importing the package, and the gate going quiet is how prompt drift shipped once.
@@ -135,6 +139,63 @@ BUILTIN_PROMPTS = {
             "}"
         ),
     },
+    "3": {
+        "general": (
+            "Your task is to solve the captcha. Read its instruction, usually at the top, and decide "
+            "what a person would do to solve it.\n\n"
+            "You are given either one screenshot or a video. Each moment of a video is labelled with "
+            "its time, like <1.3 seconds>. In a video the answer may depend on how things move or "
+            "change: what grows or shrinks, which way something turns, what appears, disappears or "
+            "moves, and in what order.\n\n"
+            "Some screenshots have numbered boxes drawn over the things you can interact with — "
+            "tiles, buttons, pieces, handles. The boxes and numbers are ours, not part of the "
+            "puzzle. When something you act on has a box, also give its number as an id. Not "
+            "everything is boxed and many screenshots have no boxes at all: a point is always "
+            "required, an id never is.\n\n"
+            "Points are on a 0–1000 scale of the image: (0, 0) is the top-left corner, (1000, 1000) "
+            "the bottom-right.\n\n"
+            "Choose ONE action:\n\n"
+            "CLICK one or more things:\n"
+            "  {\"action\": \"click\", \"points\": [[x, y], ...], \"ids\": [n, ...]}\n"
+            "  When the instruction asks for every match, a tile that is already selected (a small "
+            "checkmark, border or highlight) still counts; a tile being replaced (a large checkmark, a "
+            "picture fading out or in) does not. If nothing matches, give empty points.\n\n"
+            "DRAG pieces, one drag per piece:\n"
+            "  {\"action\": \"drag\", \"drags\": [{\"from\": [x, y], \"to\": [x, y], \"from_id\": n, "
+            "\"to_id\": n}, ...]}\n\n"
+            "SLIDE a slider: press its handle and move it until the part of the picture it moves "
+            "lines up with where it belongs — a jigsaw piece over its slot, a turned picture upright, "
+            "a shifted strip continuing the rest:\n"
+            "  {\"action\": \"slide\", \"handle\": [x, y], \"from\": [x, y], \"to\": [x, y]}\n"
+            "  \"handle\" is what you press, \"from\" a point on the part that moves, \"to\" where that "
+            "point belongs. When the piece itself is what you press, \"handle\" and \"from\" are the "
+            "same point.\n\n"
+            "PRESS AND HOLD a button. Holding fills something — a bar, a ring, the button itself — and "
+            "you let go where the fill should stop: a line or mark it must reach, else its far end:\n"
+            "  {\"action\": \"hold\", \"press\": [x, y], \"from\": [x, y], \"to\": [x, y]}\n"
+            "  \"press\" is what you hold, \"from\" where the fill starts, \"to\" where to let go.\n\n"
+            "TYPE the characters shown, exactly as printed — keep their case, add no spaces; "
+            "strike-throughs, dots and background texture are not characters:\n"
+            "  {\"action\": \"type\", \"text\": \"...\"}\n\n"
+            "REFRESH instead of solving if the puzzle looks impossible, or would take a reasonable "
+            "person more than a minute. Click the control that loads a new puzzle, usually a "
+            "circular arrow (empty points if there is none):\n"
+            "  {\"action\": \"refresh\", \"points\": [[x, y]]}\n\n"
+            "When there are several clicks or drags, list them in the order they must be done. If "
+            "the order does not matter, list them in increasing order: by number when the things are "
+            "numbered, otherwise top to bottom, and left to right within a row.\n\n"
+            "For a video, put \"t\" first: the time of the moment where your answer is clearest, in "
+            "seconds exactly as it is labelled, so the solver can wait for that moment. Leave it out "
+            "if the answer is the same throughout.\n\n"
+            "Leave out any key you have no value for. Respond ONLY with the JSON."
+        ),
+    },
+    # Generation 4 is the pointer (`captchakraken.pointer`): the board goes to the server's /pointer endpoint,
+    # which numbers its elements with the element detector, builds the prompt itself and reads the answer from one
+    # prefill. The client sends no prompt text, so there is none to drift.
+    "4": {
+        "pointer": True,
+    },
 }
 
 
@@ -213,43 +274,52 @@ def requires_auth(model: Optional[str]) -> bool:
 
 @dataclass
 class PromptSet:
+    """One generation's prompts. Generations 1 and 2 ask a prompt per family; generation 3 asks `general`, one
+    prompt for every puzzle, and has no family templates at all."""
 
     version: str
-    action_prompt: str
-    grid_template: str
+    action_prompt: Optional[str]
+    grid_template: Optional[str]
     video_template: Optional[str]
     text_template: Optional[str]
-    grid_by_type: Dict[str, str]
     source: str
+    general: Optional[str] = None
+    sends_video: bool = False
+    #: Asked at /pointer with the bare board; the server owns the prompt (generation 4).
+    pointer: bool = False
 
-    def grid_prompt(self, *, rows: int, cols: int, grid_hint: str = "",
-                    puzzle_type: Optional[str] = None) -> str:
-        if puzzle_type and puzzle_type in self.grid_by_type:
-            return self.grid_by_type[puzzle_type]
-        return self.grid_template.format(rows=rows, cols=cols,
-                                         total=rows * cols, grid_hint=grid_hint)
-
-    def video_prompt(self, n_keyframes: int) -> str:
-        n = int(n_keyframes)
+    def _family(self, template: Optional[str], family: str) -> str:
+        if template is None:
+            raise ValueError(
+                f"prompt generation {self.version} has no {family} prompt"
+                + (" — it asks one general prompt for every puzzle" if self.general else
+                   f" — model was trained before the {family} family existed. Use a model on "
+                   "generation 2 or later."))
+        return template
+
+    def pixel_prompt(self) -> str:
+        return self._family(self.action_prompt, "click-and-drag")
+
+    def grid_prompt(self, *, rows: int, cols: int, grid_hint: str = "") -> str:
+        return self._family(self.grid_template, "grid").format(rows=rows, cols=cols,
+                                                               total=rows * cols, grid_hint=grid_hint)
+
+    def video_prompt(self, n_keyframes: Optional[int] = None) -> str:
+        """The animated prompt. A video generation asks its one prompt over the clip; a keyframe generation's
+        text states how many stills it sent."""
+        if self.sends_video:
+            return self.general if self.general is not None else self._family(self.video_template, "animated-puzzle")
+        if self.general is not None:
+            # Never trained on keyframes: sending them under the general prompt would answer silently worse.
+            raise ValueError(f"prompt generation {self.version} was never trained on keyframe stills")
+        n = int(n_keyframes or 0)
         if n < 1:
             raise ValueError(f"a keyframe request needs at least one frame, got {n_keyframes}")
-        if self.video_template is None:
-            raise ValueError(
-                f"prompt generation {self.version} has no animated-puzzle prompt — "
-                f"model was trained before the video family existed. Use a model on "
-                f"generation 2 or later for animated captchas."
-            )
         listing = ", ".join(f"frame {i}" for i in range(1, n + 1))
-        return self.video_template.format(n=n, listing=listing)
+        return self._family(self.video_template, "animated-puzzle").format(n=n, listing=listing)
 
     def text_prompt(self) -> str:
-        if self.text_template is None:
-            raise ValueError(
-                f"prompt generation {self.version} has no distorted-text prompt — "
-                f"model was trained before the text family existed. Use a model on "
-                f"generation 2 or later for BotDetect/MTCaptcha/Yandex text captchas."
-            )
-        return self.text_template
+        return self._family(self.text_template, "distorted-text")
 
 
 def builtin(version: str) -> Optional[PromptSet]:
@@ -258,12 +328,14 @@ def builtin(version: str) -> Optional[PromptSet]:
         return None
     return PromptSet(
         version=str(version),
-        action_prompt=spec["action_pixel"],
-        grid_template=spec["grid"],
-        video_template=spec["video"],
-        text_template=spec["text"],
-        grid_by_type={},
+        action_prompt=spec.get("action_pixel"),
+        grid_template=spec.get("grid"),
+        video_template=spec.get("video"),
+        text_template=spec.get("text"),
         source=f"built-in v{version}",
+        general=spec.get("general"),
+        sends_video=str(version) in VIDEO_GENERATIONS,
+        pointer=bool(spec.get("pointer")),
     )
 
 
@@ -271,16 +343,17 @@ def _from_doc(doc: Dict[str, Any], source: str) -> PromptSet:
     version = str(doc.get("prompt_version", LATEST_PROMPT_VERSION))
     base = builtin(version) or builtin(LATEST_PROMPT_VERSION)
     templates = doc.get("templates") or {}
-    grid_by_type = {k.split("grid::", 1)[1]: v for k, v in templates.items()
-                    if k.startswith("grid::") and isinstance(v, str)}
     return PromptSet(
         version=version,
         action_prompt=templates.get("action_pixel") or base.action_prompt,
         grid_template=templates.get("grid") or base.grid_template,
         video_template=templates.get("video") or base.video_template,
         text_template=templates.get("text") or base.text_template,
-        grid_by_type=grid_by_type,
         source=source,
+        general=templates.get("general") or base.general,
+        # From the generation, never from the document: a template can be overridden, the way it is asked cannot.
+        sends_video=base.sends_video,
+        pointer=base.pointer,
     )
 
 
@@ -401,6 +474,10 @@ def experts(model: Optional[str]) -> Dict[PromptFamily, str]:
     mapping = entry.get("experts")
     if not isinstance(mapping, dict):
         return {}
+    if (builtin(str(entry.get("prompt_version", ""))) or builtin(LATEST_PROMPT_VERSION)).general is not None:
+        _warn(f"model {repo_id!r} is on prompt generation {entry.get('prompt_version')}, which is one model "
+              "asked one prompt; its `experts` are never routed to.")
+        return {}
     out: Dict[PromptFamily, str] = {}
     for family in PromptFamily:
         name = mapping.get(family)

package/python/src/captchakraken/selectors.py

@@ -1,10 +1,15 @@
-"""Every selector the driver knows, keyed by vendor. Mirrored in js/src/selectors.ts; keep both in the same order,
-because detection takes the first visible match in table order."""
+"""Every selector the driver knows, keyed by vendor, read from `captchakraken.config.json` at the repository root.
+
+The JS port reads the same file (js/src/selectors.ts). Detection takes the first visible match in table order, so the
+file's order is the detection order."""
 
 from __future__ import annotations
 
+import json
+import os
 from dataclasses import dataclass, fields
-from typing import Mapping, NamedTuple, Optional, Sequence, Tuple
+from pathlib import Path
+from typing import Any, Dict, Mapping, NamedTuple, Optional, Sequence, Tuple, Union
 
 from .kinds import FrameRole, RecaptchaBanner, Vendor
 
@@ -18,6 +23,9 @@ class VendorSelectors:
     challenge: Sequence[str] = ()
     # On the host page: the checkbox. Detected while `response` is empty and `checked` is not showing.
     checkbox: Sequence[str] = ()
+    # 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.
+    enclave: Sequence[str] = ()
     # 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.
     widget: Sequence[str] = ()
@@ -27,6 +35,7 @@ class VendorSelectors:
     # Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`.
     checked: Optional[str] = None
     # 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.
     box: Sequence[str] = ()
     # On the host page: the vendor painted its success state. Visibility is part of the test (see TRIBAL_KNOWLEDGE.md).
     accepted: Optional[str] = None
@@ -48,121 +57,157 @@ class VendorSelectors:
     slider_handle: Sequence[str] = ()
     # Inside the widget: the piece, measured to steer the slide and dragged directly when there is no track.
     piece: Sequence[str] = ()
+    # Inside the widget: the control that deals a new puzzle, pressed when the model answers `refresh`.
+    refresh: Sequence[str] = ()
+    # 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.
+    hold_completes: bool = False
 
 
-SELECTORS: Mapping[Vendor, VendorSelectors] = {
-    Vendor.RECAPTCHA: VendorSelectors(
-        hosts=("google.com/recaptcha", "recaptcha.net"),
-        challenge=('iframe[src*="recaptcha/api2/bframe"]',),
-        checkbox=('iframe[src*="recaptcha/api2/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", RecaptchaBanner.SELECT_MORE),
-            (".rc-imageselect-error-dynamic-more", RecaptchaBanner.DYNAMIC_MORE),
-            (".rc-imageselect-incorrect-response", RecaptchaBanner.REJECTED),
-        ),
-        blocked=(".rc-doscaptcha-header-text",),
-        passive=('iframe[src*="size=invisible"]',),
-    ),
-    # Keyed on the `hcaptcha` substring, not the apex host: challenges are served off newassets.hcaptcha.com.
-    Vendor.HCAPTCHA: VendorSelectors(
-        hosts=("hcaptcha.com",),
-        challenge=('iframe[src*="hcaptcha"][src*="frame=challenge"]',),
-        checkbox=('iframe[src*="hcaptcha"][src*="frame=checkbox"]',),
-        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",),
-    ),
-    Vendor.TURNSTILE: VendorSelectors(
-        hosts=("challenges.cloudflare.com",),
-        checkbox=('iframe[src*="challenges.cloudflare.com"]', ".cf-turnstile"),
-        response='[name="cf-turnstile-response"]',
-    ),
-    Vendor.GEETEST: VendorSelectors(
-        hosts=("geetest.com",),
-        widget=(".geetest_box", ".geetest_panel_box", ".geetest_popup_window", ".geetest_widget"),
-        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",),
-    ),
-    # 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.
-    Vendor.TENCENT: VendorSelectors(
-        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",),
-    ),
-    Vendor.YIDUN: VendorSelectors(
-        hosts=("dun.163.com", "cstaticdun.126.net", "necaptcha.nosdn.127.net"),
-        widget=(".yidun_panel", ".yidun"),
-        slider_handle=(".yidun_slider", ".yidun_jigsaw"),
-        piece=(".yidun_jigsaw",),
-    ),
-    Vendor.YANDEX: VendorSelectors(
-        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"]'),
-    ),
-    Vendor.LEMIN: VendorSelectors(
-        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"),
-    ),
-    Vendor.PROSOPO: VendorSelectors(
-        hosts=("prosopo.io",),
-        widget=(".prosopo-modalInner", ".procaptcha-checkbox"),
-    ),
-    Vendor.MTCAPTCHA: VendorSelectors(
-        hosts=("mtcaptcha.com",),
-        widget=('iframe[src*="service.mtcaptcha.com"]', 'iframe[id^="mtcaptcha-iframe"]', ".mtcaptcha", ".mtcap"),
-        text_input=("input.mtcap-inputtext", ".mtcap input[type=text]"),
-    ),
-    Vendor.BOTDETECT: VendorSelectors(
-        hosts=(),
-        widget=(".BDC_CaptchaDiv",),
-        text_input=("input[id*=captchaCode]", "input#captchaCode", "input[id*=validateCaptcha]",
-                    ".BDC_CaptchaDiv input[type=text]"),
-    ),
-    Vendor.UNKNOWN: VendorSelectors(hosts=()),
-}
-assert set(SELECTORS) == set(Vendor), "every vendor names its selectors"
-
-VENDORS: Sequence[Tuple[Vendor, VendorSelectors]] = tuple(SELECTORS.items())
-
-
-def _of_every_vendor(key: str) -> Sequence[str]:
-    assert key in {f.name for f in fields(VendorSelectors)}
-    return tuple(s for _, v in VENDORS for s in getattr(v, key))
+#: The default config: the repository's own `captchakraken.config.json` when this package runs from a checkout, so an
+#: edit there is what the solver reads, else the copy shipped inside the package (a wheel has no repository root).
+_SHIPPED_CONFIG = Path(__file__).with_name("captchakraken.config.json")
+_CHECKOUT_CONFIG = Path(__file__).resolve().parents[3] / "captchakraken.config.json"
+DEFAULT_CONFIG_PATH: Path = _CHECKOUT_CONFIG if _CHECKOUT_CONFIG.is_file() else _SHIPPED_CONFIG
 
+ConfigSource = Union[str, "os.PathLike[str]", Mapping[str, Any]]
 
-class WidgetProbe(NamedTuple):
-    vendor: Vendor
-    role: FrameRole
-    selector: str
+_FIELDS = {f.name: f for f in fields(VendorSelectors)}
+_ONE = {"response", "checked", "accepted", "fresh"}
+_GENERIC = ("submit_text", "text_input", "slider_handle", "piece")
+
+
+class SelectorConfigError(ValueError):
+    """A selector config the solver cannot use; the message names the file and the key."""
+
+
+def _read(source: ConfigSource) -> Tuple[str, Mapping[str, Any]]:
+    if isinstance(source, Mapping):
+        return "selectors", source
+    path = Path(source)
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as e:
+        raise SelectorConfigError(f"{path}: cannot be read as JSON ({e})") from None
+    if not isinstance(doc, Mapping):
+        raise SelectorConfigError(f"{path}: the top level must be an object")
+    return str(path), doc
+
+
+def _strings(where: str, value: Any) -> Tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise SelectorConfigError(f"{where}: must be a list of strings")
+    return tuple(value)
+
+
+def _entry(where: str, raw: Any, hosts_required: bool = True) -> VendorSelectors:
+    if not isinstance(raw, Mapping):
+        raise SelectorConfigError(f"{where}: must be an object")
+    kw: Dict[str, Any] = {}
+    for key, value in raw.items():
+        at = f"{where}.{key}"
+        if key == "note" or key.startswith("_"):
+            continue
+        if key not in _FIELDS:
+            raise SelectorConfigError(f"{at}: not a selector field (one of {', '.join(_FIELDS)})")
+        if key in _ONE:
+            if value is not None and not isinstance(value, str):
+                raise SelectorConfigError(f"{at}: must be one selector string")
+            kw[key] = value
+        elif key == "hold_completes":
+            if not isinstance(value, bool):
+                raise SelectorConfigError(f"{at}: must be true or false")
+            kw[key] = value
+        elif key == "banners":
+            if not isinstance(value, list):
+                raise SelectorConfigError(f"{at}: must be a list of [selector, verdict] pairs")
+            pairs = []
+            for i, pair in enumerate(value):
+                if not (isinstance(pair, list) and len(pair) == 2 and isinstance(pair[0], str)):
+                    raise SelectorConfigError(f"{at}[{i}]: must be a [selector, verdict] pair")
+                try:
+                    pairs.append((pair[0], RecaptchaBanner(pair[1])))
+                except ValueError:
+                    raise SelectorConfigError(
+                        f"{at}[{i}]: verdict {pair[1]!r} is not one of {[b.value for b in RecaptchaBanner]}") from None
+            kw[key] = tuple(pairs)
+        else:
+            kw[key] = _strings(at, value)
+    if "hosts" not in kw:
+        if hosts_required:
+            raise SelectorConfigError(f"{where}.hosts: missing (an empty list when the vendor has no host of its own)")
+        kw["hosts"] = ()
+    return VendorSelectors(**kw)
+
+
+#: The element detector a config may choose (see `pointer.detector`).
+DETECTOR_CHOICES = ("auto", "standard", "lite")
+
+
+class SelectorConfig(NamedTuple):
+    """A loaded config: the caller's own entry, every vendor's in detection order, the generic fallbacks, and which
+    element detector runs."""
+    custom: Optional[VendorSelectors]
+    vendors: Mapping[Vendor, VendorSelectors]
+    generic: Mapping[str, Tuple[str, ...]]
+    detector: str = "auto"
 
 
-# Every host-page selector with what it names, in detection order: open challenges, then checkboxes, then inline widgets.
-WIDGET_PROBES: Sequence[WidgetProbe] = tuple(
-    WidgetProbe(vendor, role, selector)
-    for role, key in ((FrameRole.CHALLENGE, "challenge"), (FrameRole.CHECKBOX, "checkbox"), (FrameRole.UNKNOWN, "widget"))
-    for vendor, s in VENDORS
-    for selector in getattr(s, key))
+def _parse(name: str, doc: Mapping[str, Any], base: Optional[SelectorConfig]) -> SelectorConfig:
+    for key in doc:
+        if not key.startswith("_") and key not in ("detector", "custom", "vendors", "generic"):
+            raise SelectorConfigError(f"{name}: {key}: not a config key (detector, custom, vendors, generic)")
+    detector = base.detector if base else "auto"
+    if "detector" in doc:
+        if not isinstance(doc["detector"], str) or doc["detector"].strip().lower() not in DETECTOR_CHOICES:
+            raise SelectorConfigError(f"{name}: detector: {doc['detector']!r} is not one of {', '.join(DETECTOR_CHOICES)}")
+        detector = doc["detector"].strip().lower()
+    custom = base.custom if base else None
+    if "custom" in doc:
+        custom = None if doc["custom"] is None else _entry(f"{name}: custom", doc["custom"], hosts_required=False)
+    raw_vendors = doc.get("vendors", {})
+    if not isinstance(raw_vendors, Mapping):
+        raise SelectorConfigError(f"{name}: vendors: must be an object keyed by vendor")
+    vendors: Dict[Vendor, VendorSelectors] = dict(base.vendors) if base else {}
+    for key, raw in raw_vendors.items():
+        if key.startswith("_"):
+            continue
+        try:
+            vendor = Vendor(key)
+        except ValueError:
+            raise SelectorConfigError(
+                f"{name}: vendors.{key}: not a vendor this solver knows; a captcha of your own goes under `custom`") from None
+        vendors[vendor] = _entry(f"{name}: vendors.{key}", raw)
+    if base is None and set(vendors) != set(Vendor):
+        missing = sorted(v.value for v in set(Vendor) - set(vendors))
+        raise SelectorConfigError(f"{name}: vendors: every vendor must have an entry; missing {missing}")
+    raw_generic = doc.get("generic", {})
+    if not isinstance(raw_generic, Mapping):
+        raise SelectorConfigError(f"{name}: generic: must be an object")
+    generic: Dict[str, Tuple[str, ...]] = dict(base.generic) if base else {}
+    for key, value in raw_generic.items():
+        if key.startswith("_"):
+            continue
+        if key not in _GENERIC:
+            raise SelectorConfigError(f"{name}: generic.{key}: not a generic list (one of {', '.join(_GENERIC)})")
+        generic[key] = _strings(f"{name}: generic.{key}", value)
+    if base is None and set(generic) != set(_GENERIC):
+        raise SelectorConfigError(f"{name}: generic: missing {sorted(set(_GENERIC) - set(generic))}")
+    return SelectorConfig(custom, vendors, generic, detector)
 
-RESPONSE_SELECTORS: Sequence[str] = tuple(s.response for _, s in VENDORS if s.response)
-ACCEPTED_SELECTORS: Sequence[str] = tuple(s.accepted for _, s in VENDORS if s.accepted)
+
+def load_config(source: Optional[ConfigSource] = None) -> SelectorConfig:
+    """The shipped default, or `source` (a path or a parsed object) laid over it: a key it gives replaces the default's
+    `custom`, one vendor's whole entry, or one generic list. Raises SelectorConfigError naming the bad key."""
+    default = _parse(*_read(DEFAULT_CONFIG_PATH), base=None)
+    if source is None or (not isinstance(source, Mapping) and Path(source) == DEFAULT_CONFIG_PATH):
+        return default
+    return _parse(*_read(source), base=default)
+
+
+DEFAULT_CONFIG: SelectorConfig = load_config()
+#: Every vendor's entry, in detection order, as the default config gives it.
+SELECTORS: Mapping[Vendor, VendorSelectors] = DEFAULT_CONFIG.vendors
 
 _LOWER = "translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"
 
@@ -172,23 +217,71 @@ def submit_by_text(text: str) -> str:
     return f"xpath=.//button[contains({_LOWER}, '{text}')] | .//div[@role=\"button\" and contains({_LOWER}, '{text}')]"
 
 
-# A real Verify/Next/Submit/Skip first; the vendor-named controls are fallbacks.
-SUBMIT_SELECTORS: Sequence[str] = (*map(submit_by_text, ("verify", "next", "submit", "skip")), *_of_every_vendor("submit"))
-
-# Vendor-named first, generic last: the driver takes the first visible match, and a generic selector
-# reached before the vendor's own is how a captcha's answer ends up in a login form's username box.
-TEXT_INPUT_VENDOR_SELECTORS: Sequence[str] = _of_every_vendor("text_input")
-TEXT_INPUT_SELECTORS: Sequence[str] = (
-    *TEXT_INPUT_VENDOR_SELECTORS,
-    '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",
-)
-# `[draggable=true]` is absent: HTML5 DnD fires dragstart, not pointermove.
-SLIDER_HANDLE_SELECTORS: Sequence[str] = (
-    *_of_every_vendor("slider_handle"),
-    '[role="slider"]', "[aria-valuenow]",
-    '[class*="slider"][class*="btn"]', '[class*="slider"][class*="button"]',
-    '[class*="slide"][class*="handle"]', '[class*="drag"][class*="thumb"]',
-)
-PIECE_SELECTORS: Sequence[str] = (*_of_every_vendor("piece"), '[class*="puzzle"][class*="piece"]', '[class*="jigsaw"]')
+class WidgetProbe(NamedTuple):
+    vendor: Vendor
+    role: FrameRole
+    selector: str
+
+
+_DETECTED_BY = ("challenge", "checkbox", "widget")
+
+
+class SelectorTable:
+    """The table one solver detects and drives with: a selector config's vendors, plus its `custom` entry when it has one.
+
+    `config` is a path, a parsed object or a loaded SelectorConfig, laid over the shipped default (see `load_config`).
+    `custom` (the older `custom_selectors=`) replaces the config's own `custom`. A custom entry is reported as
+    `Vendor.UNKNOWN` and searched before the built-in vendors, because the caller wrote it for the page in front of them.
+    """
+
+    def __init__(self, custom: Optional[VendorSelectors] = None,
+                 config: Union[ConfigSource, SelectorConfig, None] = None) -> None:
+        loaded = config if isinstance(config, SelectorConfig) else load_config(config)
+        custom = custom if custom is not None else loaded.custom
+        if custom is not None and not any(getattr(custom, key) for key in _DETECTED_BY):
+            raise SelectorConfigError(
+                "custom selectors name nothing to detect: give the entry a `widget`, `challenge` or `checkbox`")
+        self.config = loaded
+        self.selectors: Mapping[Vendor, VendorSelectors] = (
+            {Vendor.UNKNOWN: custom, **{v: s for v, s in loaded.vendors.items() if v != Vendor.UNKNOWN}}
+            if custom is not None else loaded.vendors)
+        self.vendors: Sequence[Tuple[Vendor, VendorSelectors]] = tuple(self.selectors.items())
+        # Every host-page selector with what it names, in detection order: open challenges, then checkboxes, then
+        # inline widgets.
+        self.widget_probes: Sequence[WidgetProbe] = tuple(
+            WidgetProbe(vendor, role, selector)
+            for role, key in zip((FrameRole.CHALLENGE, FrameRole.CHECKBOX, FrameRole.UNKNOWN), _DETECTED_BY)
+            for vendor, s in self.vendors
+            for selector in getattr(s, key))
+        self.enclave: Sequence[str] = self._of_every_vendor("enclave")
+        self.response: Sequence[str] = tuple(s.response for _, s in self.vendors if s.response)
+        self.accepted: Sequence[str] = tuple(s.accepted for _, s in self.vendors if s.accepted)
+        # A real Verify/Next/Submit/Skip/Confirm first; the vendor-named controls are fallbacks.
+        self.submit: Sequence[str] = (*map(submit_by_text, loaded.generic["submit_text"]),
+                                      *self._of_every_vendor("submit"))
+        # Vendor-named first, generic last: the driver takes the first visible match, and a generic selector
+        # reached before the vendor's own is how a captcha's answer ends up in a login form's username box.
+        self.text_input_vendor: Sequence[str] = self._of_every_vendor("text_input")
+        self.text_input: Sequence[str] = (*self.text_input_vendor, *loaded.generic["text_input"])
+        # `[draggable=true]` is absent from the generic handles: HTML5 DnD fires dragstart, not pointermove.
+        self.slider_handle: Sequence[str] = (*self._of_every_vendor("slider_handle"), *loaded.generic["slider_handle"])
+        self.refresh: Sequence[str] = self._of_every_vendor("refresh")
+        self.piece: Sequence[str] = (*self._of_every_vendor("piece"), *loaded.generic["piece"])
+
+    def _of_every_vendor(self, key: str) -> Sequence[str]:
+        assert key in {f.name for f in fields(VendorSelectors)}
+        return tuple(s for _, v in self.vendors for s in getattr(v, key))
+
+
+DEFAULT_TABLE = SelectorTable(config=DEFAULT_CONFIG)
+VENDORS = DEFAULT_TABLE.vendors
+WIDGET_PROBES = DEFAULT_TABLE.widget_probes
+ENCLAVE_SELECTORS = DEFAULT_TABLE.enclave
+RESPONSE_SELECTORS = DEFAULT_TABLE.response
+ACCEPTED_SELECTORS = DEFAULT_TABLE.accepted
+SUBMIT_SELECTORS = DEFAULT_TABLE.submit
+TEXT_INPUT_VENDOR_SELECTORS = DEFAULT_TABLE.text_input_vendor
+TEXT_INPUT_SELECTORS = DEFAULT_TABLE.text_input
+SLIDER_HANDLE_SELECTORS = DEFAULT_TABLE.slider_handle
+REFRESH_SELECTORS = DEFAULT_TABLE.refresh
+PIECE_SELECTORS = DEFAULT_TABLE.piece

package/python/src/captchakraken/server_manager.py

@@ -1,3 +1,4 @@
+import json
 import os
 import shutil
 import signal
@@ -10,6 +11,7 @@ from urllib.parse import urlparse
 import requests
 
 from . import config
+from .clipvideo import media_io_kwargs
 
 STATE_DIR = config.state_dir()
 LOCK_FILE = STATE_DIR / "vllm.lock"
@@ -67,6 +69,18 @@ def _read_pid() -> "int | None":
 
 
 def build_serve_command() -> "list[str]":
+    from . import prompts
+
+    if prompts.resolve(config.lora_adapter()).pointer:
+        detector = os.environ["CAPTCHA_POINTER_DETECTOR"]
+        return [
+            sys.executable, "-m", "captchakraken.pointer.server",
+            "--model", config.base_model(),
+            "--detector", detector,
+            "--host", os.getenv("CAPTCHA_POINTER_HOST", "127.0.0.1"),
+            "--port", str(config.port()),
+            "--gpu-memory-utilization", str(config.gpu_memory_utilization()),
+        ]
     return [
         _vllm_bin() or "vllm", "serve", config.base_model(),
         "--reasoning-parser", "qwen3",
@@ -78,6 +92,10 @@ def build_serve_command() -> "list[str]":
         "--trust-remote-code",
         "--port", str(config.port()),
         "--lora-modules", f"{config.lora_name()}={config.lora_adapter()}",
+        # A video-generation model watches an animation as one JPEG frame sequence; without these vLLM refuses the
+        # video or resamples it to its own frame count, and the time the model answers with names the wrong moment.
+        "--limit-mm-per-prompt", json.dumps({"image": 8, "video": 1}),
+        "--media-io-kwargs", json.dumps(media_io_kwargs()),
         *config.extra_serve_args(),
     ]