captchakraken 2.1.0 → 2.3.0

package/LICENSE

@@ -0,0 +1,105 @@
+CaptchaKraken Source-Available License v1.0
+Copyright (c) 2026 JobHarvest / JWriter20. 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
+copyright holder (collectively, the "Software"). By using the Software you agree
+to these terms. If you do not agree, do not use the Software.
+
+================================================================================
+1. GRANT
+================================================================================
+Subject to the restrictions below, you are granted a worldwide, royalty-free,
+non-exclusive license to use, copy, modify, and distribute the Software, and to
+incorporate it into your own products and services.
+
+================================================================================
+2. PERMITTED USES
+================================================================================
+You MAY use the Software for:
+
+  (a) Personal, non-commercial use, research, and education.
+
+  (b) Commercial use INSIDE a larger product or service that delivers
+      substantial value BEYOND captcha solving itself — that is, where captcha
+      solving is an internal, enabling component rather than the product.
+
+  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.
+      - QA, testing, and accessibility tooling.
+      - Any application where the captcha solve is a means to an end the user
+        is actually paying for.
+
+================================================================================
+3. PROHIBITED USES
+================================================================================
+You MAY NOT, without a separate written commercial agreement from the copyright
+holder:
+
+  (a) Sell, resell, rent, or otherwise offer for a fee any captcha-SOLVING
+      service, product, or API whose primary value is solving captchas,
+      where that service is powered by the Software or its model outputs.
+
+  (b) Distribute "thin wrappers" around the Software whose primary purpose is
+      captcha solving — including but not limited to browser extensions,
+      hosted endpoints, SaaS products, or CLIs that simply expose the
+      Software's solving capability to end users.
+
+  (c) Expose, proxy, or relay the responses or outputs of the Software's LoRA
+      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.
+
+================================================================================
+4. MODEL OUTPUTS
+================================================================================
+Outputs produced by the model weights/adapters are subject to Sections 2 and 3
+to the same extent as the Software itself. Reselling or API-relaying those
+outputs as a captcha-solving service is prohibited under Section 3(c).
+
+================================================================================
+5. REDISTRIBUTION
+================================================================================
+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.
+
+================================================================================
+6. TRADEMARKS
+================================================================================
+This license does not grant permission to use the trade names, trademarks, or
+product names of the copyright holder, except as required to describe the origin
+of the Software.
+
+================================================================================
+7. NO WARRANTY
+================================================================================
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+================================================================================
+8. RESPONSIBLE USE
+================================================================================
+You are responsible for ensuring your use of the Software complies with all
+applicable laws, the terms of service of any site you interact with, and
+applicable anti-fraud and computer-access statutes. The copyright holder does
+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.
+
+--------------------------------------------------------------------------------
+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
+case, ask by opening an issue or messaging the maintainer on GitHub:
+https://github.com/JWriter20/CaptchaKraken
+--------------------------------------------------------------------------------

package/README.md

@@ -51,4 +51,6 @@ Puppeteer users wrap the page once with `fromPuppeteer(page)`.
 
 ## License
 
-GPL-3.0-or-later.
+**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).

package/dist/playwright-types.d.ts

@@ -42,6 +42,8 @@ export interface PlaywrightElementHandle {
     /** Screenshot just this element to a PNG file (the only option the solver passes). */
     screenshot(options?: {
         path?: string;
+        timeout?: number;
+        animations?: 'disabled' | 'allow';
     }): Promise<Buffer>;
     /** The content document of an `<iframe>` element handle, or null if not a frame. */
     contentFrame(): Promise<PlaywrightFrame | null>;

package/dist/solver.d.ts

@@ -15,6 +15,9 @@ export declare class CaptchaKrakenSolver {
     private cvWorkerPending;
     private cvWorkerBuf;
     private solutionCache;
+    private state;
+    private lastSubmitFrameHash;
+    private solveSessionId;
     constructor(config?: CaptchaKrakenConfig);
     solve(page: Page): Promise<SolveResult | void>;
     private solveImpl;
@@ -245,6 +248,70 @@ export declare class CaptchaKrakenSolver {
      */
     private solveRecaptchaGrid;
     private getSolution;
+    /**
+     * Query the model for `initialShot`, then guard against the captcha frame
+     * having changed DURING inference. reCAPTCHA/hCaptcha fade fresh tiles in over
+     * ~1s; if new imagery painted while the model was generating, its answer
+     * targets a stale ("undeveloped") frame and its tile picks / bboxes no longer
+     * line up with what's on screen. After the model returns we re-screenshot the
+     * element and diff it against the frame we sent (reusing the `check-movement`
+     * primitive); if it moved beyond the threshold we discard the answer and
+     * re-solve on the fresh frame, up to `maxStaleFrameReSolves` times, then act on
+     * the latest answer rather than spin.
+     *
+     * `runQuery` performs the actual model call for a given screenshot path (the
+     * caller wraps it in idle-wander where appropriate); it is re-invoked with the
+     * fresh path on each re-solve. Token usage from every query — including
+     * discarded ones — is accumulated, since those tokens were really spent. The
+     * caller owns `initialShot`; every fresh frame captured here is created and
+     * cleaned up here. Best-effort: a screenshot/diff failure falls through to the
+     * answer already in hand.
+     */
+    private solveFrameFreshnessGuarded;
+    /**
+     * Screenshot the captcha element to a throwaway temp frame and diff it against
+     * `priorPath` (the frame we sent the model). Returns true when the frame
+     * changed beyond `threshold` — i.e. tiles faded in / refreshed since. Reuses
+     * the persistent CV worker's `check-movement` (falling back to a one-shot
+     * subprocess), the same frame-diff the settle detectors use. Cleans up its own
+     * temp frame. Best-effort: any screenshot/diff failure returns false so the
+     * caller acts on the answer it already has rather than spinning.
+     */
+    private captchaFrameChangedSince;
+    /** Record a challenge-state transition. No-op for behaviour; logs the change
+     *  (via gridDebug, so only when CAPTCHA_DEBUG=1) for offline diagnosis. */
+    private setState;
+    /**
+     * Screenshot the challenge element to a throwaway file and return its sha1
+     * content hash (or null on failure). Used to tell whether the frame has
+     * changed (e.g. the post-submit transition to the next round). Cleans up.
+     */
+    private elementFrameHash;
+    /**
+     * Monitor the challenge element until its pixels stop changing (settled), or
+     * until it's clear it never will (animated / video). Polls screenshots and
+     * diffs consecutive frames with `check-movement` (the persistent CV worker).
+     * Returns:
+     *   'settled'  — `settleFrames` consecutive frame-pairs showed no movement;
+     *                safe to screenshot for the model.
+     *   'animated' — it kept moving right up to `animatedChallengeAfterMs` without
+     *                ever settling → very likely a video/animated puzzle.
+     *   'timeout'  — neither happened within `settleTimeoutMs` (proceed best-effort).
+     *
+     * Note this is a *pixel* settle; the caller pairs it with the DOM-level
+     * `waitForHcaptchaChallengeImages` so a static loading frame (spinner on grey,
+     * below the pixel threshold) isn't mistaken for painted tiles. Cleans up.
+     */
+    private waitForElementSettled;
+    /**
+     * After a submit we EXPECT the challenge frame to change (advance to the next
+     * round, or close because it was accepted). Poll until the element's content
+     * hash differs from `sinceHash` — the transition beginning — so we never
+     * screenshot/solve the pre-transition frame again. Returns true once it
+     * changed, false if it never changed within `postSubmitChangeTimeoutMs` (e.g.
+     * it was already the final state). Best-effort.
+     */
+    private waitForChangeSince;
     /**
      * Run `fn` (typically the model query) while idly drifting the cursor over
      * the captcha, so the mouse behaves like a human weighing the options instead