captchakraken 2.9.0 → 3.1.0

package/dist/watcher.d.ts

@@ -1,99 +1,26 @@
 /**
- * Auto-solve watcher — install once, and captchas are solved as they appear.
- *
- * WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
- * The obvious implementation is a `MutationObserver` inside the page that calls
- * out through `exposeBinding`. That is faster to react, and it is also the one
- * design that cannot be made stealthy on every platform: `exposeBinding` puts a
- * function on `window` and an observer is script the page can enumerate. On
- * Camoufox both are sandboxed and invisible; on vanilla Playwright or Puppeteer
- * they are not, and a captcha vendor is exactly the party that looks.
- *
- * So the watcher injects NOTHING. It drives the same `detectCaptcha()` the
- * solver already uses, from the driver side, on a timer. Consequences worth
- * knowing:
- *
- *   - Nothing is added to the page on ANY platform, so there is no new
- *     detection surface to reason about per launcher.
- *   - On Camoufox the probe's DOM reads run in Camoufox's isolated Juggler
- *     world for free — that is its default for all Playwright evaluation
- *     (`main_world_eval` / an `mw:` prefix is the opt-OUT). The watcher never
- *     opts out, so it is isolated there by construction, not by special-casing.
- *   - Reaction time is bounded by `intervalMs`, not by the mutation itself.
- *     A captcha that appears just after a tick waits up to one interval.
- *
- *
- * 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
- * browser-compat.test.ts.
- * DETECTION IS THE SOLVER'S, NOT A COPY
- * The trigger is `solver.detectCaptcha(page)`, the same method `solve()` calls,
- * so "what counts as a captcha" has exactly one definition. An earlier sketch
- * kept a union of the vendor selectors here for a cheaper single-roundtrip
- * probe; it drifted from VENDOR_WIDGET_LOCATORS the first time a vendor was
- * added, which is the failure this indirection exists to prevent.
- *
- * ```typescript
- * const solver = new CaptchaKrakenSolver();
- * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
- * // ... your automation runs; captchas are solved underneath it ...
- * await watcher.stop();
- * ```
+ * Polls; injects nothing. An exposed binding or a MutationObserver is script the page can enumerate under
+ * vanilla Playwright or Puppeteer, and a captcha vendor is exactly the party that looks. See TRIBAL_KNOWLEDGE.md.
  */
 import { PlaywrightPage as Page } from './playwright-types';
 import { SolveResult } from './types';
-/**
- * The slice of the solver the watcher drives.
- *
- * Structural rather than an import of `CaptchaKrakenSolver` so this module has
- * no runtime dependency on solver.ts (which imports this one for the `watch()`
- * method — a real cycle under CommonJS), and so tests can drive it with a fake.
- */
+/** Structural, not the solver class: a real import here would be a CommonJS cycle. Detection reuses detectCaptcha because a copied selector union drifted the first time a vendor was added. */
 export interface WatchableSolver {
     detectCaptcha(page: Page): Promise<unknown | null>;
     solve(page: Page): Promise<SolveResult | void>;
 }
 export interface WatchOptions {
-    /**
-     * Milliseconds between detection probes. Default 1000.
-     *
-     * This is the latency floor for noticing a captcha, and each tick costs one
-     * `detectCaptcha()` — a handful of selector queries. Below ~250ms you are
-     * paying real CPU for latency the solve itself (seconds) makes irrelevant.
-     */
+    /** Default 1000; below ~250 is wasted CPU. */
     intervalMs?: number;
-    /** Stop automatically after this many successful solves. Default: unlimited. */
     maxSolves?: number;
-    /**
-     * Wait this long after a solve THROWS before probing again. Default 5000.
-     *
-     * Without it a permanently unsupported challenge — an invisible reCAPTCHA v3,
-     * say — turns the watcher into a hot loop that re-attempts and re-bills every
-     * `intervalMs` forever.
-     */
+    /** Default 5000. Without it a permanently unsupported challenge is a hot loop that re-attempts and re-bills every interval forever. */
     errorBackoffMs?: number;
-    /** Called after each solve that returns a result. Exceptions here are swallowed. */
     onSolved?: (result: SolveResult) => void | Promise<void>;
-    /**
-     * Called when detection or solving throws. Exceptions here are swallowed.
-     *
-     * Errors are reported, never fatal: `NoCaptchaFoundError` fires routinely
-     * when a widget disappears between the probe and the solve, and a watcher
-     * that died on it would be useless.
-     */
     onError?: (error: unknown) => void | Promise<void>;
 }
 export interface CaptchaWatcher {
-    /** Stop probing and resolve once any in-flight solve has finished. */
     stop(): Promise<void>;
-    /** False once stopped, the page closed, or `maxSolves` was reached. */
     readonly running: boolean;
-    /** Successful solves so far. */
     readonly solves: number;
 }
 export declare function watchPage(solver: WatchableSolver, page: Page, options?: WatchOptions): CaptchaWatcher;

package/dist/watcher.js

@@ -1,58 +1,9 @@
 "use strict";
-/**
- * Auto-solve watcher — install once, and captchas are solved as they appear.
- *
- * WHY THIS IS A POLL AND NOT AN INJECTED OBSERVER
- * The obvious implementation is a `MutationObserver` inside the page that calls
- * out through `exposeBinding`. That is faster to react, and it is also the one
- * design that cannot be made stealthy on every platform: `exposeBinding` puts a
- * function on `window` and an observer is script the page can enumerate. On
- * Camoufox both are sandboxed and invisible; on vanilla Playwright or Puppeteer
- * they are not, and a captcha vendor is exactly the party that looks.
- *
- * So the watcher injects NOTHING. It drives the same `detectCaptcha()` the
- * solver already uses, from the driver side, on a timer. Consequences worth
- * knowing:
- *
- *   - Nothing is added to the page on ANY platform, so there is no new
- *     detection surface to reason about per launcher.
- *   - On Camoufox the probe's DOM reads run in Camoufox's isolated Juggler
- *     world for free — that is its default for all Playwright evaluation
- *     (`main_world_eval` / an `mw:` prefix is the opt-OUT). The watcher never
- *     opts out, so it is isolated there by construction, not by special-casing.
- *   - Reaction time is bounded by `intervalMs`, not by the mutation itself.
- *     A captcha that appears just after a tick waits up to one interval.
- *
- *
- * 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
- * browser-compat.test.ts.
- * DETECTION IS THE SOLVER'S, NOT A COPY
- * The trigger is `solver.detectCaptcha(page)`, the same method `solve()` calls,
- * so "what counts as a captcha" has exactly one definition. An earlier sketch
- * kept a union of the vendor selectors here for a cheaper single-roundtrip
- * probe; it drifted from VENDOR_WIDGET_LOCATORS the first time a vendor was
- * added, which is the failure this indirection exists to prevent.
- *
- * ```typescript
- * const solver = new CaptchaKrakenSolver();
- * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
- * // ... your automation runs; captchas are solved underneath it ...
- * await watcher.stop();
- * ```
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.watchPage = watchPage;
-/** A page that has closed, where the launcher exposes that (Playwright and Puppeteer both do). */
 function isPageClosed(page) {
     return typeof page.isClosed === 'function' ? page.isClosed() : false;
 }
-/** Report to a user callback without letting its failure reach the loop. */
 async function report(fn, value) {
     if (!fn)
         return;
@@ -60,7 +11,6 @@ async function report(fn, value) {
         await fn(value);
     }
     catch {
-        // A throwing callback is the caller's bug and must not stop the watcher.
     }
 }
 function watchPage(solver, page, options = {}) {
@@ -69,12 +19,8 @@ function watchPage(solver, page, options = {}) {
     const maxSolves = options.maxSolves ?? Infinity;
     let running = true;
     let solves = 0;
-    // Resolved by the loop on its way out, so stop() can await a solve in flight.
-    // Definite assignment: the Promise executor runs synchronously, so `finished`
-    // is set before any code below can reach it — TS cannot prove that itself.
     let finished;
     const done = new Promise((resolve) => { finished = resolve; });
-    // Held so stop() can cut a pending sleep short instead of waiting it out.
     let wake = null;
     const sleep = (ms) => new Promise((resolve) => {
         const timer = setTimeout(() => { wake = null; resolve(); }, ms);
@@ -91,8 +37,6 @@ function watchPage(solver, page, options = {}) {
                 try {
                     if (!(await solver.detectCaptcha(page)))
                         continue;
-                    // Re-check: detectCaptcha can take a moment, and stop() during it
-                    // should not be followed by a fresh multi-second solve.
                     if (!running)
                         break;
                     const result = await solver.solve(page);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "captchakraken",
-  "version": "2.9.0",
-  "description": "Captcha solver for Playwright and Puppeteer. Finds the captcha, reads the puzzle with a fine-tuned Qwen3.5-9B vision model, and clicks, drags, slides or types through to a token — reCAPTCHA, hCaptcha, GeeTest, NetEase Yidun, Tencent, Lemin, Prosopo, Turnstile and distorted text. Hosted API or self-hosted.",
+  "version": "3.1.0",
+  "description": "Captcha solver for Playwright and Puppeteer. Finds the captcha, reads the puzzle with a fine-tuned Qwen3.5-9B vision model, and clicks, drags, slides or types through to a token \u2014 reCAPTCHA, hCaptcha, GeeTest, NetEase Yidun, Tencent, Lemin, Prosopo, Turnstile and distorted text. Hosted API or self-hosted.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "NOTICE",
     "python",
     "scripts",
+    "AGENTS.md",
     "LICENSE"
   ],
   "scripts": {
@@ -16,6 +18,7 @@
     "demo": "tsx examples/demoSites.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "tsc -p tsconfig.test.json && node --test .test-build/*.test.js",
+    "coverage": "tsc -p tsconfig.test.json && c8 node --test .test-build/*.test.js",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/setup-python.js"
   },
@@ -49,8 +52,12 @@
     "url": "https://github.com/JWriter20/CaptchaKraken/issues"
   },
   "homepage": "https://github.com/JWriter20/CaptchaKraken#readme",
+  "dependencies": {
+    "cursory-js": "2.0.1"
+  },
   "devDependencies": {
-    "@types/node": "^24.10.2",
-    "typescript": "^5.9.3"
+    "@types/node": "24.10.2",
+    "c8": "12.0.0",
+    "typescript": "5.9.3"
   }
 }

package/python/AGENTS.md

@@ -0,0 +1,122 @@
+# captchakraken (PyPI)
+
+The Python **engine and CLI**: OpenCV grid detection plus a planner that asks a
+fine-tuned vision model what to do, and a page driver that performs it in a
+Playwright browser.
+
+It is not a browser and, by default, not the model either. It installs no
+browser — bring your own — and every inference goes to a model endpoint you
+point it at. The `serve` extra is what turns this box into that endpoint.
+
+Repo, guides and the full agent guide:
+<https://github.com/JWriter20/CaptchaKraken>
+
+---
+
+## 1. Point it at a model, first
+
+| You have | Do this |
+|---|---|
+| No GPU | Use the hosted API — add the account MCP server, `npx -y captchakraken-mcp`, call `sign_in` then `create_api_key` |
+| A GPU, and want it local | `pip install "captchakraken[serve]"`, then `captchakraken server start` |
+| Your own vLLM server | `export VLLM_BASE_URL=…/v1` and `export CAPTCHA_KRAKEN_API_KEY=…` |
+
+`create_api_key` writes the key and endpoint to `~/.captchakraken/credentials`
+(mode 0600) and the client reads that file by itself, so the MCP path needs **no
+environment variables at all**. The key is never printed into the conversation.
+
+A local endpoint auto-starts on the first solve; `CAPTCHA_KRAKEN_AUTOSTART=0`
+turns that off. A non-localhost `VLLM_BASE_URL` is never started or managed for
+you.
+
+## 2. Install
+
+```bash
+pip install captchakraken            # the client: grid detection + planner + CLI
+pip install "captchakraken[serve]"   # ...and the vLLM serving stack, to host it
+```
+
+Python 3.11+.
+
+## 3. Solve
+
+Synchronous Playwright:
+
+```python
+from playwright.sync_api import sync_playwright
+from captchakraken import PageSolver
+
+with sync_playwright() as p:
+    page = p.chromium.launch().new_page()
+    page.goto("https://www.google.com/recaptcha/api2/demo")
+    result = PageSolver().solve(page)
+    print(result.is_solved)
+```
+
+`PageSolver().watch(page)` installs a background watcher instead, for when you
+do not know if or when a captcha will appear; stop it with `.stop()`.
+
+No browser, just an image:
+
+```bash
+captchakraken path/to/captcha.png    # prints a JSON click plan
+```
+
+Other CLI modes, all printing JSON: `captchakraken server start|stop|status|run`
+manages a local vLLM server, `captchakraken fetch` updates weights and the
+serving stack together, and the OpenCV tool calls (`find-grid`, `find-checkbox`,
+`get-numbered-grid`, `detect-selected`, …) are exposed one per subcommand. The
+module docstring of `captchakraken/cli.py` lists every mode with its arguments.
+
+## 4. Errors
+
+`PageSolver.solve()` raises from `captchakraken.page_solver`:
+`NoCaptchaFoundError` (no interactive widget — usually not a failure),
+`UnsupportedChallengeError`, `AnimatedChallengeError` (the challenge could not
+be *recorded*), `PageClosedError`, and `CaptchaSolveError`, which is the base
+class of the other four — catch it last or it swallows them. The TypeScript
+port raises none of these; it exports one error class and throws plain `Error`
+otherwise.
+
+Refusals from the hosted API raise `CaptchaKrakenAPIError` (exported from the
+package root). **Branch on `.code`, never on the message text** — the codes are
+the contract, the wording is not: `insufficient_credits`, `missing_api_key`,
+`invalid_api_key`, `rate_limited`, `request_too_large`, `account_suspended`,
+`upstream_unavailable`. Retrying a `403` that means "no licence" will never
+succeed.
+
+## 5. If you drive the model yourself
+
+Grid screenshots must be sent with **cell numbers drawn on them** — the client
+runs `find_grid`, renders the numbered overlay, and sends that image, because
+the model reads those labels and was never trained to invent a numbering.
+Without the overlay reCAPTCHA 4×4 scores zero without erroring. Image area is
+also clamped into the `pixel_budget` the model declares in
+`captchakraken/models.json`. Use the shipped client unless you have a reason not
+to, and never hardcode a model name — read it from the config, or the prompt
+generation and the weights drift apart.
+
+## Rules for agents
+
+- **Never invent a number.** Every accuracy, latency and price figure we publish
+  is on one page —
+  [docs/benchmarks.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/benchmarks.md).
+  Quote it as written; do not derive, round, or convert anything, and do not
+  read a static-image rate as a promise about a browser run.
+- **Never print an API key** into a transcript, a log, or a commit. Use
+  `create_api_key`, which writes it to disk instead. `captchakraken.env` and
+  `.env` hold keys and are never committed.
+- **Abyss is what our hosted API serves, and it is never downloadable.** The
+  current client names an Abyss expert on every request to our endpoint and is
+  answered by Abyss; an older client, or a request that names no model, gets
+  Twilight v1.2, because its prompts belong to that generation. Nothing about it
+  is gated on the account. Do not suggest weights, a download or a workaround
+  for it, and do not quote accuracy figures for it — none are published. Verify
+  what is serving with `GET /v1/models`.
+- **Respect the licence.** Building automation with this is fine; selling the
+  solve, or shipping it inside a browser or automation product, is not. See
+  [LICENSE](./LICENSE) and
+  [docs/licensing.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/licensing.md).
+- **Changing this package's own code?** Its rules are in
+  [CONTRIBUTING.md](https://github.com/JWriter20/CaptchaKraken/blob/main/CONTRIBUTING.md),
+  not here.

package/python/NOTICE

@@ -0,0 +1,36 @@
+CaptchaKraken
+Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
+
+This product includes third-party software. The notices below are required by
+those components' licences and do not change the terms of the CaptchaKraken
+Source-Available License, which governs everything in this repository that is
+not listed here.
+
+────────────────────────────────────────────────────────────────────────────
+Cursory  —  mouse trajectory generation
+────────────────────────────────────────────────────────────────────────────
+
+  cursory      https://github.com/Vinyzu/cursory      (Python, PyPI: cursory)
+  cursory-js   https://github.com/JWriter20/cursory-js  (TypeScript, npm: cursory-js)
+
+  Copyright (c) Vinyzu and the cursory-js contributors.
+  Licensed under the GNU Lesser General Public License, version 3 or later
+  (LGPL-3.0-or-later). A copy is available at https://www.gnu.org/licenses/lgpl-3.0.html
+
+  HOW WE USE IT, AND WHY THAT MATTERS. Both are ORDINARY INSTALLED
+  DEPENDENCIES — `cursory` is declared in python/pyproject.toml and `cursory-js`
+  in js/package.json, and each is resolved by the user's own package manager at
+  install time. Neither is vendored into this repository, copied into our
+  sources, or bundled into a build artifact: the TypeScript build is `tsc`, which
+  leaves `require('cursory-js')` as a runtime import rather than inlining it, and
+  `js/scripts/copy-python.mjs` copies only our own `python/` tree.
+
+  That arrangement is the one the LGPL is written for, and it is what lets this
+  product remain under its own licence. It also means a user may replace either
+  library with a modified version of their own — reinstall the package, and the
+  driver picks it up — which is the freedom section 4 of the LGPL requires be
+  preserved. Do not vendor, inline, or bundle either one without taking legal
+  advice first; doing so is the change that would put this obligation somewhere
+  other than where it now sits.
+
+  We have not modified either library.

package/python/README.md

@@ -111,8 +111,7 @@ actions = solver.solve("captcha.png")
 ```
 
 Pure-OpenCV tool subcommands (no model): `find-grid`, `find-checkbox`,
-`detect-selected`, `grid-cell-states`, `find-move`, `find-movable`, and a
-persistent `serve` worker the browser driver polls.
+`detect-selected`, `grid-cell-states`, and a persistent `serve` worker the browser driver polls.
 
 ## Configuration (model-agnostic)
 

package/python/examples/README.md

@@ -44,6 +44,16 @@ If `CAMOUFOX_BINARY` is unset, camoufox falls back to its default binary
 source ../captchakraken.env       # VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY
 ```
 
+Running the model locally on **Ollama** or **LM Studio** instead? Those load
+GGUF, so they need the GGUF build rather than the AWQ/FP8 downloads — see
+[Self-hosting → GGUF](../../docs/self-hosting.md#gguf-for-ollama-lm-studio-and-llamacpp),
+then check the wiring with one image and no browser:
+
+```bash
+python examples/with_local_gguf.py path/to/captcha.png
+python examples/with_local_gguf.py path/to/text-captcha.png --text
+```
+
 ## Run
 
 ```bash

package/python/examples/_harness.py

@@ -1,27 +1,3 @@
-"""
-Shared runner for the CaptchaKraken Python demos.
-
-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
@@ -38,17 +14,10 @@ from captchakraken.page_solver import CaptchaSolveError, PageSolver
 class DemoSpec:
     name: str
     url: str
-    vendor: str  # "recaptcha" | "hcaptcha" — advisory; PageSolver auto-detects
+    vendor: str
 
 
 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.")
@@ -69,21 +38,8 @@ def spec_from_argv(default: DemoSpec, argv=None) -> DemoSpec:
 
 
 def _launch_kwargs() -> dict:
-    # 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")
     if binary:
         kw["executable_path"] = binary
@@ -91,13 +47,6 @@ def _launch_kwargs() -> dict:
 
 
 def _page_kwargs() -> dict:
-    """Record the session when CAPTCHA_DEMO_VIDEO_DIR is set.
-
-    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 {}
@@ -107,27 +56,17 @@ def _page_kwargs() -> dict:
 
 
 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
+    except Exception:
         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.
-    """
     inp = out = 0
     for u in usage or []:
         inp += int(u.get("prompt_tokens", u.get("inputTokens", 0)) or 0)
@@ -175,11 +114,9 @@ def run_demo(spec: DemoSpec) -> None:
             page = browser.new_page(**_page_kwargs())
             try:
                 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
+                except Exception:
                     pass
                 page.wait_for_timeout(3000)
 
@@ -196,10 +133,8 @@ def run_demo(spec: DemoSpec) -> None:
                 err = e
                 reason = _explain(spec.vendor, False, e)
             finally:
-                # 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
+    except Exception as e:
         err = e
         reason = _explain(spec.vendor, False, e)
 
@@ -228,10 +163,6 @@ def _report(spec, *, ok, total_s, solve_s, inp, out, tps, reason, video=None):
         print(f"  reason        : {reason}")
     print(f"{line}\n")
 
-    # 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:

package/python/examples/demoHcaptcha.py

@@ -1,16 +1,3 @@
-"""
-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                     # 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.
-"""
-
 from _harness import DemoSpec, run_demo
 
 if __name__ == "__main__":

package/python/examples/demoRecaptcha.py

@@ -1,13 +1,3 @@
-"""
-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                     # this demo page
-    python examples/demoRecaptcha.py https://your.site/  # any URL
-"""
-
 from _harness import DemoSpec, run_demo
 
 if __name__ == "__main__":

package/python/examples/watch_playwright.py

@@ -1,26 +1,3 @@
-"""
-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
@@ -36,16 +13,14 @@ def main() -> int:
         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
+        watcher.run(timeout_ms=SECONDS * 1000)
 
         print(f"stopped after {watcher.solves} solve(s)")
         browser.close()