captchakraken 2.4.0 → 2.6.0

package/python/LICENSE

@@ -1,5 +1,5 @@
-CaptchaKraken Source-Available License v1.0
-Copyright (c) 2026 JobHarvest / JWriter20. All rights reserved.
+CaptchaKraken Source-Available License v1.1
+Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
 
 This license governs use of the CaptchaKraken software in this repository and of
 the associated machine-learning model weights and LoRA adapters published by the
@@ -26,12 +26,17 @@ You MAY use the Software for:
 
   Illustrative (non-exhaustive) examples of PERMITTED commercial use:
       - Web scrapers and data-collection pipelines.
-      - Stealth / anti-detection browsers and browser automation frameworks
-        that use the Software as one internal capability.
+      - Browser automation you build and operate for your own purposes.
       - QA, testing, and accessibility tooling.
       - Any application where the captcha solve is a means to an end the user
         is actually paying for.
 
+  (c) RUNNING the Software alongside a stealth, anti-detection, or antidetect
+      browser — Camoufox, Puppeteer, Playwright, or any similar tool — to
+      automate your own work, commercially or otherwise. Section 3(d) restricts
+      SHIPPING the Software as a feature of such a browser to other people. It
+      does not restrict USING it with one.
+
 ================================================================================
 3. PROHIBITED USES
 ================================================================================
@@ -51,7 +56,23 @@ holder:
       models (e.g. bounding boxes, tile selections, click plans) through a paid
       or public API as a captcha-solving service.
 
-  In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
+  (d) Embed, bundle, preinstall, or otherwise ship the Software — or a client,
+      wrapper, plugin, or extension for it — as a captcha-solving capability of
+      any stealth browser, anti-detection or antidetect browser, browser
+      profile or identity manager, or browser-automation product or platform
+      that you distribute, host, or otherwise offer to third parties. This
+      applies whether the Software ships inside your distribution, is fetched
+      on demand, or is merely wired up and advertised as a supported
+      integration, and it applies whether or not you charge for it.
+
+      This restriction is about DISTRIBUTION, not use. Nothing in it limits
+      Section 2(c): a person who uses such a browser may install and run the
+      Software with it freely.
+
+  In short: you may BUILD WITH this Software, and you may USE it with whatever
+  browser you like — but you may not SELL THE SOLVE, and you may not SHIP THE
+  SOLVE as a feature of a stealth browser or automation product you hand to
+  other people.
 
 ================================================================================
 4. MODEL OUTPUTS
@@ -65,6 +86,7 @@ outputs as a captcha-solving service is prohibited under Section 3(c).
 ================================================================================
 If you redistribute the Software (modified or not), you must retain this license
 and this notice, and you must not remove or alter the restrictions in Section 3.
+The right to redistribute granted by Section 1 is subject to Section 3(d).
 
 ================================================================================
 6. TRADEMARKS
@@ -95,11 +117,29 @@ not endorse using the Software to violate any third party's terms or rights.
 9. COMMERCIAL LICENSING
 ================================================================================
 For uses prohibited under Section 3 — including selling captcha-solving as a
-service — contact the copyright holder to discuss a separate commercial license.
+service, and shipping the Software as a built-in capability of a stealth browser
+or automation product — contact the copyright holder to discuss a separate
+commercial license. These uses are licensable; they are not categorically
+refused.
+
+================================================================================
+10. VERSION HISTORY
+================================================================================
+v1.1 — Section 3(d) added: shipping the Software as a captcha-solving feature of
+       a stealth/anti-detection browser or automation product distributed to
+       third parties now requires a commercial license. Section 2(c) added to
+       make clear that USING the Software with such a browser remains permitted.
+       The v1.0 text listed "stealth / anti-detection browsers" as an
+       illustrative PERMITTED commercial use; that example is removed.
+v1.0 — Initial release.
+
+Each version applies to the releases distributed under it. Copies obtained under
+v1.0 remain governed by v1.0.
 
 --------------------------------------------------------------------------------
 This text is a license, not legal advice. If the boundary between a permitted
-"value-add" product and a prohibited "thin wrapper" is unclear for your use
+"value-add" product and a prohibited "thin wrapper", or between using the
+Software with a browser and shipping it as part of one, is unclear for your use
 case, ask by opening an issue or messaging the maintainer on GitHub:
 https://github.com/JWriter20/CaptchaKraken
 --------------------------------------------------------------------------------

package/python/README.md

@@ -22,6 +22,20 @@ if you want to run the model yourself. The one-command
 [`setup.sh`](https://github.com/JWriter20/CaptchaKraken) installs `[serve]`,
 downloads the weights, and writes an env file for you.
 
+## No GPU? Use the hosted API
+
+Point the client at `https://api.captchakraken.com/v1` and run no model at all.
+Sign in at [captchakraken.com/signin](https://captchakraken.com/signin) for a
+`ck_live_…` key, or let the MCP server write one for you:
+
+```bash
+claude mcp add captchakraken -- npx -y captchakraken-mcp
+# then call sign_in, then create_api_key
+```
+
+`create_api_key` writes the key and the endpoint to `~/.captchakraken/credentials`,
+which the client reads on its own — **no environment variables needed**.
+
 ## Hands-off server
 
 The vLLM server is managed for you. On your first solve, if the configured
@@ -59,15 +73,18 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 
 | Variable | Meaning | Default |
 |---|---|---|
-| `VLLM_BASE_URL` | Inference endpoint | `http://localhost:8000/v1` |
-| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | `EMPTY` |
-| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `Qwen/Qwen3.5-9B` |
-| `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken_v1` |
-| `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha` |
+| `VLLM_BASE_URL` | Inference endpoint | `~/.captchakraken/credentials`, else `http://localhost:8000/v1` |
+| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | `~/.captchakraken/credentials`, else `EMPTY` |
+| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `RedHatAI/Qwen3.5-9B-FP8-dynamic` |
+| `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken-Lora-v1.2` |
+| `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha-v12` |
 | `CAPTCHA_KRAKEN_AUTOSTART` | `0` disables local auto-start | `1` |
 
 ## License
 
-**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
-Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
-solve itself** or ship a thin wrapper (browser extension, hosted solving API).
+**CaptchaKraken Source-Available License v1.1** — see [LICENSE](./LICENSE).
+Build *with* it (scrapers, QA tooling) and run it against **any** browser you
+like, stealth or not. You may **not sell the solve itself**, ship a thin wrapper
+(browser extension, hosted solving API), or **bundle it as a built-in feature of
+a stealth/antidetect browser you distribute** — using it with one is fine. Those
+three are licensable, not categorically refused: open an issue to ask.

package/python/examples/README.md

@@ -66,3 +66,39 @@ HEADLESS=0 python examples/demoRecaptcha.py    # watch the browser
 `gen speed` = model output tokens ÷ solve seconds. Failure reasons the harness
 reports: unreachable vLLM server, an unsupported hCaptcha puzzle (drag/video),
 the challenge iframe never appearing, or the model returning no matching tiles.
+
+## Playwright, and the auto-solver
+
+| File | What it shows |
+|---|---|
+| `with_playwright.py` | Vanilla Playwright — no adapter, 2 added lines |
+| `watch_playwright.py` | The auto-solver: install once, solves as they appear |
+
+```bash
+pip install playwright && playwright install chromium
+
+export VLLM_BASE_URL=https://api.captchakraken.com/v1
+export CAPTCHA_KRAKEN_API_KEY=ck_live_...
+
+python examples/with_playwright.py
+python examples/watch_playwright.py https://your.site/page 60
+```
+
+Use `sync_playwright`, not `async_playwright`: `PageSolver` mirrors the
+synchronous API, and a sync handle cannot be driven from inside an event loop.
+
+## There is no Puppeteer path in Python
+
+The TypeScript port ships `fromPuppeteer()` because Puppeteer is a first-class
+Node library. Python has no equivalent worth pointing you at:
+
+- **pyppeteer** last released 2.0.0 in **February 2024**, and pins
+  `urllib3 <2.0.0` and `websockets <11.0` — which conflicts directly with
+  CaptchaKraken's own `requests` dependency, so the two cannot co-install
+  cleanly.
+- It is **async-only**, and this driver is synchronous. Even resolving the
+  dependency conflict, a sync `PageSolver` cannot be driven from asyncio.
+
+Playwright *is* the Python answer, and `patchright` and `camoufox` are the
+stealth-patched builds of it — all three duck-type identically, so the examples
+above work unchanged with any of them.

package/python/examples/_harness.py

@@ -1,39 +1,87 @@
 """
 Shared runner for the CaptchaKraken Python demos.
 
-The Python port is the *engine* (OpenCV detection + the vLLM planner). These demos
-launch a real stealth browser (camoufox, using the binary from your fork —
-JWriter20/camoufox releases; see README.md), navigate to a captcha demo site,
-open the challenge, screenshot it, and run the engine on that frame. They report
-token-generation speed, total time, and whether the engine produced a valid
-solution — plus a best-effort reason when it didn't.
-
-Note: full click-replay + multi-round verification in a live page is what the
-TypeScript port (`captchakraken`) does end-to-end. Here we validate the
-engine + model + server on a real challenge frame.
+Launches a real stealth browser (camoufox, using the binary from your fork —
+JWriter20/camoufox releases; see README.md), navigates to a page with a captcha
+on it, and solves it THE WAY PRODUCTION DOES: `PageSolver` finds the widget,
+opens the challenge, clicks, submits, and decides whether the vendor accepted.
+It reports token-generation speed, total time, and whether the solve succeeded,
+plus a best-effort reason when it didn't.
+
+Point it at any URL:
+
+    python examples/demoHcaptcha.py                       # the built-in demo page
+    python examples/demoHcaptcha.py https://your.site/    # anything else
+    python examples/demoHcaptcha.py https://your.site/ --headed
+
+This used to be image-in / actions-out — screenshot the challenge, ask the
+engine for a click plan, print how many tiles it would have clicked, and stop.
+That measured the model but never the driver, and a recording of it showed a
+captcha nobody touched. `captchakraken.page_solver` is the Python mirror of the
+TypeScript driver, so both ports now demo the same end-to-end path, which is
+what CLAUDE.md rule 1c asks for.
 """
 
+import argparse
+import json
 import os
-import tempfile
+import sys
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 from camoufox.sync_api import Camoufox
 
-from captchakraken import CaptchaSolver
-from captchakraken.action_types import ClickAction
-from captchakraken.solver import UnsupportedCaptchaError
+from captchakraken.page_solver import CaptchaSolveError, PageSolver
 
 
 @dataclass
 class DemoSpec:
     name: str
     url: str
-    vendor: str  # "recaptcha" | "hcaptcha"
+    vendor: str  # "recaptcha" | "hcaptcha" — advisory; PageSolver auto-detects
+
+
+def spec_from_argv(default: DemoSpec, argv=None) -> DemoSpec:
+    """Let any demo point at an arbitrary page.
+
+    The vendor stays a default rather than being inferred from the URL: it only
+    selects the wording of a failure explanation, and PageSolver detects the
+    actual widget itself. Guessing it from a hostname would be wrong exactly on
+    the pages worth demoing — your own site, embedding someone else's captcha.
+    """
+    ap = argparse.ArgumentParser(
+        description=f"CaptchaKraken demo — {default.name}",
+        epilog="With no URL, runs against the built-in demo page.")
+    ap.add_argument("url", nargs="?", default=default.url,
+                    help=f"page to solve (default: {default.url})")
+    ap.add_argument("--vendor", default=default.vendor,
+                    choices=("hcaptcha", "recaptcha"),
+                    help="only affects failure wording; the solver auto-detects")
+    ap.add_argument("--name", default=None, help="label for the report")
+    ap.add_argument("--headed", action="store_true",
+                    help="show the browser (same as HEADLESS=0)")
+    args = ap.parse_args(argv)
+
+    if args.headed:
+        os.environ["HEADLESS"] = "0"
+    name = args.name or (default.name if args.url == default.url else args.url)
+    return replace(default, url=args.url, vendor=args.vendor, name=name)
 
 
 def _launch_kwargs() -> dict:
-    kw = dict(headless=os.getenv("HEADLESS", "1") != "0", humanize=True, geoip=False)
+    # HUMANIZE defaults OFF, same as tests/live-solve/solve_fixture.py, and for
+    # the same measured reason. The solver already moves the mouse along its own
+    # 60-point trajectory (`_smooth_move` -> `generate_trajectory`); camoufox's
+    # humanize juggler then expands EACH of those 60 micro-moves into its own
+    # humanised sub-trajectory — 60 nested traversals to cover one straight
+    # line. On this demo page that is 25-52s per click round instead of ~5s,
+    # which does not merely look slow: it blows the 120s overall_solve_timeout
+    # and reports a solvable captcha as "not solved". What a vendor scores is
+    # the trajectory SHAPE, and that comes from generate_trajectory either way.
+    # Set HUMANIZE=1 to drive it the other way against a vendor that
+    # fingerprints motion.
+    kw = dict(headless=os.getenv("HEADLESS", "1") != "0",
+              humanize=os.getenv("HUMANIZE", "0") != "0", geoip=False)
     # Point camoufox at YOUR fork's binary. If unset, camoufox uses its default
     # cached binary (`python -m camoufox fetch`).
     binary = os.getenv("CAMOUFOX_BINARY") or os.getenv("CAMOUFOX_EXECUTABLE_PATH")
@@ -42,117 +90,157 @@ def _launch_kwargs() -> dict:
     return kw
 
 
-def _capture_challenge(page, spec: DemoSpec) -> str:
-    """Reach the challenge iframe and screenshot it to a temp PNG. Returns the path.
+def _page_kwargs() -> dict:
+    """Record the session when CAPTCHA_DEMO_VIDEO_DIR is set.
 
-    Raises RuntimeError with a human message if the challenge never appears.
+    Plain Playwright options, but they only produce a video on a build whose
+    screencast actually emits frames. Stock camoufox accepts every one of them
+    and writes either nothing or a blank 0.96s file — no error anywhere — so a
+    caller that cares should check the size of what it gets back.
+    """
+    out = os.getenv("CAPTCHA_DEMO_VIDEO_DIR")
+    if not out:
+        return {}
+    w, _, h = os.getenv("CAPTCHA_DEMO_VIDEO_SIZE", "1280x800").partition("x")
+    return {"record_video_dir": out,
+            "record_video_size": {"width": int(w), "height": int(h)}}
+
+
+def _finish_video(page):
+    """Close the context so the container is finalised; return the file path.
+
+    Playwright writes the video on CONTEXT close, not page close — reading
+    video.path() before that names a file which may never appear.
+    """
+    video = getattr(page, "video", None)
+    if video is None:
+        return None
+    try:
+        page.context.close()
+        return video.path()
+    except Exception:  # noqa: BLE001 — a missing video must not fail the demo
+        return None
+
+
+def _tokens(usage) -> tuple[int, int]:
+    """(input, output) over a SolveResult's usage log.
+
+    Accepts both spellings because the two ports report different ones and this
+    is a demo, not a place to discover a key mismatch as a zero.
     """
-    out = tempfile.NamedTemporaryFile(suffix=".png", delete=False).name
-
-    if spec.vendor == "recaptcha":
-        anchor = page.wait_for_selector('iframe[src*="/recaptcha/api2/anchor"]', timeout=30_000)
-        frame = anchor.content_frame()
-        frame.click("#recaptcha-anchor", timeout=15_000)
-        challenge = page.wait_for_selector('iframe[src*="/recaptcha/api2/bframe"]', timeout=30_000)
-        # Let the tiles paint.
-        page.wait_for_timeout(2500)
-        challenge.screenshot(path=out)
-        return out
-
-    if spec.vendor == "hcaptcha":
-        box = page.wait_for_selector('iframe[src*="hcaptcha.com"][src*="checkbox"], iframe[title*="checkbox"]',
-                                     timeout=30_000)
-        box.content_frame().click("#checkbox, div[role=checkbox]", timeout=15_000)
-        challenge = page.wait_for_selector('iframe[title*="hCaptcha challenge"], iframe[src*="hcaptcha.com"][src*="frame=challenge"]',
-                                           timeout=30_000)
-        page.wait_for_timeout(2500)
-        challenge.screenshot(path=out)
-        return out
-
-    raise RuntimeError(f"unknown vendor {spec.vendor!r}")
-
-
-def _tokens_per_sec(solver: CaptchaSolver, elapsed_s: float) -> tuple[int, int, float]:
-    """(input_tokens, output_tokens, tokens/sec) from the planner's usage log."""
     inp = out = 0
-    for u in getattr(solver.planner, "token_usage", []) or []:
-        inp += int(u.get("prompt_tokens", 0) or 0)
-        out += int(u.get("completion_tokens", 0) or 0)
-    tps = out / elapsed_s if out and elapsed_s > 0 else 0.0
-    return inp, out, tps
+    for u in usage or []:
+        inp += int(u.get("prompt_tokens", u.get("inputTokens", 0)) or 0)
+        out += int(u.get("completion_tokens", u.get("outputTokens", 0)) or 0)
+    return inp, out
 
 
-def _explain(vendor: str, err: Exception) -> str:
-    msg = str(err).lower()
-    if isinstance(err, UnsupportedCaptchaError) or "cannot solve" in msg or "unsupported" in msg:
+def _explain(vendor: str, solved: bool, err) -> str:
+    msg = str(err or "").lower()
+    if "unsupported" in msg or "cannot solve" in msg:
         if vendor == "hcaptcha":
-            return ("hCaptcha served a non-grid challenge (drag / video / choose-the-card). "
-                    "The engine handles image grids + checkboxes only — re-run to try for a grid.")
-        return "Not a supported grid/checkbox challenge — re-run to try again."
+            return ("hCaptcha served a challenge type the solver does not handle "
+                    "yet (drag / video / choose-the-card) — re-run for a grid.")
+        return "Not a supported challenge type — re-run to try again."
+    if "no captcha" in msg or "nocaptchafound" in msg:
+        return ("No captcha widget was found on that page. Check the URL, or "
+                "the widget may load only after an interaction.")
     if "vllm" in msg or "connection" in msg or "refused" in msg or "max retries" in msg:
-        return ("Could not reach the vLLM server — is it up and is VLLM_BASE_URL correct? "
-                "(A local server auto-starts only if captchakraken[serve] is installed.)")
-    if "timeout" in msg or "wait_for_selector" in msg:
-        return "The challenge iframe never appeared (slow network, blocked widget, or the checkbox auto-passed)."
-    return str(err) or "Unknown failure."
+        return ("Could not reach the vLLM server — is it up and is VLLM_BASE_URL "
+                "correct? (A local server auto-starts only with captchakraken[serve].)")
+    if "timeout" in msg:
+        return "Timed out — the page or challenge never became interactable."
+    if err:
+        return str(err)
+    if not solved:
+        return ("The answer was submitted but the vendor did not accept it. Most "
+                "often IP reputation or fingerprint flagging rather than a wrong "
+                "answer — try a cleaner IP or a residential proxy.")
+    return "Unknown failure."
 
 
 def run_demo(spec: DemoSpec) -> None:
+    spec = spec_from_argv(spec)
+
     t0 = time.time()
     ok = False
     reason = None
     inp = out = 0
-    tps = 0.0
     solve_s = 0.0
-    plan_desc = "-"
+    video_path = None
+    err = None
 
     try:
         with Camoufox(**_launch_kwargs()) as browser:
-            page = browser.new_page()
-            page.goto(spec.url, wait_until="domcontentloaded", timeout=60_000)
-            shot = _capture_challenge(page, spec)
-
-            solver = CaptchaSolver()
-            s0 = time.time()
+            page = browser.new_page(**_page_kwargs())
             try:
-                actions = solver.solve(shot, puzzle_source=spec.vendor)
+                page.goto(spec.url, wait_until="domcontentloaded", timeout=60_000)
+                # The widget's iframe injects after DOMContentLoaded on every
+                # vendor; the TS harness waits the same way.
+                try:
+                    page.wait_for_load_state("networkidle", timeout=15_000)
+                except Exception:  # noqa: BLE001 — a busy page is still solvable
+                    pass
+                page.wait_for_timeout(3000)
+
+                s0 = time.time()
+                try:
+                    result = PageSolver().solve(page)
+                finally:
+                    solve_s = time.time() - s0
+                ok = bool(result.is_solved)
+                inp, out = _tokens(result.token_usage)
+                if not ok:
+                    reason = _explain(spec.vendor, ok, None)
+            except CaptchaSolveError as e:
+                err = e
+                reason = _explain(spec.vendor, False, e)
             finally:
-                solve_s = time.time() - s0
-            inp, out, tps = _tokens_per_sec(solver, solve_s)
-
-            acts = actions if isinstance(actions, list) else [actions]
-            clicks = [a for a in acts if isinstance(a, ClickAction) and (a.target_bounding_boxes or [])]
-            n_tiles = sum(len(a.target_bounding_boxes or []) for a in clicks)
-            if n_tiles > 0:
-                ok = True
-                plan_desc = f"click plan: {n_tiles} tile(s)/target(s)"
-            else:
-                plan_desc = f"actions: {[type(a).__name__ for a in acts]}"
-                reason = ("The model returned no tiles to click — either none matched the prompt, "
-                          "or the challenge frame wasn't a clean grid. Re-run to try again.")
-    except Exception as err:  # noqa: BLE001 — demo: report, don't traceback
-        reason = _explain(spec.vendor, err)
-
+                # In the finally so a failed run still yields its recording —
+                # that is the run you most want to watch back.
+                video_path = _finish_video(page)
+    except Exception as e:  # noqa: BLE001 — demo: report, don't traceback
+        err = e
+        reason = _explain(spec.vendor, False, e)
+
+    tps = out / solve_s if out and solve_s > 0 else 0.0
     _report(spec, ok=ok, total_s=time.time() - t0, solve_s=solve_s,
-            inp=inp, out=out, tps=tps, plan=plan_desc, reason=reason)
+            inp=inp, out=out, tps=tps, reason=reason, video=video_path)
 
 
 def _fmt(s: float) -> str:
     return f"{s:.1f}s" if s >= 1 else f"{int(s * 1000)}ms"
 
 
-def _report(spec, *, ok, total_s, solve_s, inp, out, tps, plan, reason):
+def _report(spec, *, ok, total_s, solve_s, inp, out, tps, reason, video=None):
     line = "─" * 52
     print(f"\n{line}")
-    print(f"  CaptchaKraken demo (engine) — {spec.name}")
+    print(f"  CaptchaKraken demo — {spec.name}")
     print(f"  {spec.url}")
     print(line)
-    print(f"  result        : {'✓ engine produced a solution' if ok else '✗ no solution'}")
-    print(f"  {plan}")
+    print(f"  result        : {'✓ SOLVED' if ok else '✗ not solved'}")
     print(f"  total time    : {_fmt(total_s)}   (solve: {_fmt(solve_s)})")
     print(f"  tokens        : {inp} in / {out} out")
     print(f"  gen speed     : {f'~{tps:.1f} tok/s' if tps > 0 else 'n/a'}")
+    if video:
+        print(f"  video         : {video}")
     if reason:
         print(f"  reason        : {reason}")
     print(f"{line}\n")
-    raise SystemExit(0 if ok else 1)
+
+    # Optional machine-readable copy of the same report, appended as one JSON
+    # line. The printed block is for a human reading a terminal; anything that
+    # wants to keep the result — compare two adapters, chart tok/s over a
+    # week — should not have to scrape it back out of that text.
+    record = os.getenv("CAPTCHA_DEMO_RECORD")
+    if record:
+        with open(record, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps({
+                "demo": spec.name, "url": spec.url, "vendor": spec.vendor,
+                "ok": ok, "reason": reason,
+                "total_s": round(total_s, 1), "solve_s": round(solve_s, 1),
+                "input_tokens": inp, "output_tokens": out,
+                "tokens_per_sec": round(tps, 1), "video": video,
+            }) + "\n")
+
+    sys.exit(0 if ok else 1)

package/python/examples/demoHcaptcha.py

@@ -4,7 +4,8 @@ Engine demo: run CaptchaKraken on the standard hCaptcha demo page.
     pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
     pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
     source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
-    python examples/demoHcaptcha.py
+    python examples/demoHcaptcha.py                     # this demo page
+    python examples/demoHcaptcha.py https://your.site/  # any URL
 
 Note: hCaptcha randomly serves non-grid puzzles (drag / video / choose-the-card),
 which the engine does not handle yet — the report says so; re-run for a grid.

package/python/examples/demoRecaptcha.py

@@ -4,7 +4,8 @@ Engine demo: run CaptchaKraken on Google's standard reCAPTCHA v2 demo page.
     pip install -e ".[serve]"     # engine + serving stack (or [.] against a remote server)
     pip install camoufox && python -m camoufox fetch   # or set CAMOUFOX_BINARY to your fork binary
     source ../captchakraken.env    # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
-    python examples/demoRecaptcha.py
+    python examples/demoRecaptcha.py                     # this demo page
+    python examples/demoRecaptcha.py https://your.site/  # any URL
 """
 
 from _harness import DemoSpec, run_demo

package/python/examples/watch_playwright.py

@@ -0,0 +1,56 @@
+"""
+The auto-solver: install once, and captchas are solved as they appear.
+
+`solve(page)` handles whatever is on the page right now. `watch(page)` is for
+when you do not know WHERE in a script a challenge will interrupt you.
+
+    python examples/watch_playwright.py [url] [seconds]
+
+TWO SHAPES, because this port is synchronous:
+
+    solver.watch(page).run()        # blocking — hold this page clean
+    w = solver.watch(page)          # cooperative — you own the cadence
+    while working():
+        w.poll_once()
+
+The TypeScript twin returns a background handle instead. That difference is
+Playwright's, not ours: a sync handle is bound to the greenlet that created it,
+so a worker thread cannot drive the page.
+
+It injects nothing into the page on any launcher. Under camoufox its DOM reads
+run in the isolated Juggler world by default.
+"""
+
+import sys
+
+from playwright.sync_api import sync_playwright
+
+from captchakraken import PageSolver
+
+URL = sys.argv[1] if len(sys.argv) > 1 else "https://www.google.com/recaptcha/api2/demo"
+SECONDS = int(sys.argv[2]) if len(sys.argv) > 2 else 30
+
+
+def main() -> int:
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        page = browser.new_page()
+
+        # ── install once, then let it work ───────────────────────────────────
+        watcher = PageSolver().watch(
+            page,
+            on_solved=lambda r: print("✅ solved one:", r.is_solved),
+            on_error=lambda e: print("solve failed:", e),
+        )
+        # ─────────────────────────────────────────────────────────────────────
+
+        page.goto(URL)
+        watcher.run(timeout_ms=SECONDS * 1000)   # blocks; solves as they appear
+
+        print(f"stopped after {watcher.solves} solve(s)")
+        browser.close()
+        return 0 if watcher.solves else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/python/examples/with_playwright.py

@@ -0,0 +1,43 @@
+"""
+Vanilla Playwright + CaptchaKraken.
+
+No adapter, and no browser dependency in the package: the driver duck-types the
+Playwright surface, so a real `sync_playwright` page satisfies it as-is — as do
+patchright's and camoufox's.
+
+    pip install captchakraken playwright && playwright install chromium
+    export VLLM_BASE_URL=https://api.captchakraken.com/v1
+    export CAPTCHA_KRAKEN_API_KEY=ck_live_...
+    python examples/with_playwright.py [url]
+
+SYNC, NOT ASYNC. `PageSolver` mirrors the synchronous Playwright API. A sync
+handle cannot be driven from inside an event loop, so `async_playwright` pages
+cannot be solved — use `sync_playwright`, as here.
+"""
+
+import sys
+
+from playwright.sync_api import sync_playwright
+
+from captchakraken import PageSolver
+
+URL = sys.argv[1] if len(sys.argv) > 1 else "https://www.google.com/recaptcha/api2/demo"
+
+
+def main() -> int:
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        page = browser.new_page()
+        page.goto(URL)
+
+        # ── the whole integration: construct, solve ──────────────────────────
+        result = PageSolver().solve(page)
+        # ─────────────────────────────────────────────────────────────────────
+
+        print("✅ solved" if result.is_solved else "❌ not solved")
+        browser.close()
+        return 0 if result.is_solved else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())