@opencraw/captcha-tesseract 0.0.3 → 0.0.5

package/README.md

@@ -23,7 +23,7 @@ import { tesseractReader } from '@opencraw/captcha-tesseract'
 
 export const captchaSolvers = [
   tesseractReader({
-    charset:       'A-Za-z0-9',   // the characters the site uses: a list with ranges, or /[A-HJ-NP-Z2-9]/
+    charset:       '1-9A-HJ-NP-Zabdefghnqrtu', // the characters the site draws: a list with ranges, or /[A-HJ-NP-Z2-9]/
     length:        6,             // a read of any other length is refreshed, never submitted
     caseSensitive: true,
     audit:         (read) => console.log(read.outcome, read.text, read.confidence),
@@ -63,7 +63,11 @@ Then name it in a form captcha step, placed after the steps that fill the form:
 6. **Check the read.** Only characters from the charset are kept. The read must be exactly `length` characters,
    and every character must be read with at least `minConfidence`. The least sure character decides, because
    Tesseract's whole-word confidence is too noisy for six loose characters.
-7. **Refresh or fill.**
+7. **Cross-check it** (`crossCheck`, on by default). Tesseract reads a line with context, and it can bend a
+   character to fit its neighbours: a `4` after lowercase letters comes out `a` or `d`, at 90% confidence or more,
+   so no confidence threshold catches it. The reader pulls the characters apart (a white gap between each run of
+   inked columns) and reads the image again. The read passes only when both reads agree.
+8. **Refresh or fill.**
    - A read that fails the check makes the reader click `refresh` and read again, up to `refreshes` times. It
      never submits it. This is the only check possible before the form is posted, and it is free: refreshing
      posts no form and risks no lockout. A last character cut off by the image's edge is the usual failure.
@@ -80,7 +84,8 @@ verdict back to the reader, which passes it to `audit`.
 | `charset` | `A-Za-z0-9` | The characters the captcha uses: a list with `a-z` ranges, or a one-character RegExp class. |
 | `length` | any | The code's length, or `[min, max]`. |
 | `caseSensitive` | `false` | Whether `a` and `A` differ. When `false`, each letter allows its other case too. |
-| `minConfidence` | 50 | The least confidence (0–100) every character must have. |
+| `minConfidence` | 30 | The least confidence (0–100) every character must have. A floor against junk reads: on real images the cross-check, not the confidence, catches the wrong reads. |
+| `crossCheck` | `true` | Read the image a second time with the characters spaced apart, and submit only when both reads agree. |
 | `refreshes` | 5 | Reads (each after a refresh) before an attempt gives up. |
 | `preprocess` | | `{ scale: 3, threshold: 'otsu', invert: 'auto', median: false, padding: 10 }` |
 | `pageSegMode` | 7 | Tesseract page segmentation: `7` one line, `8` one word, `13` a raw line. `7` measured best. |
@@ -94,7 +99,7 @@ verdict back to the reader, which passes it to `audit`.
 ## The audit
 
 Each read reaches `audit` once, with:
-- `text` (filtered) and `raw` (as Tesseract read it);
+- `text` (filtered) and `raw` (as Tesseract read it), and `second` (the cross-check's read, when one was made);
 - `confidence` (the least sure character) and `symbols` (each character with its confidence and box);
 - `image` and `cleaned` (PNG buffers of the captured image and of what Tesseract saw);
 - `url`, `attempt`, `read` (the read within the attempt), `durationMs`;
@@ -109,22 +114,31 @@ working reader, run the built-in `manual` solver headed: a person types the code
 
 ## Accuracy
 
-These figures were measured when the package was written.
-
-**The e2e corpus:** 6-character mixed-case codes in a bold sans-serif, 140×40, drawn like the Vahan report's.
-Over 80 codes:
-- 78% read right;
-- 10% refused and refreshed;
-- 13% read wrong and submitted, so the site refuses them and the engine tries again.
-
-Of the reads that were submitted, 86% were right. With 5 attempts, a captcha is left unsolved in fewer than one
-run in 10,000.
-
-**Real Vahan images:** of 5, 4 were read right, including one whose last character is clipped. The fifth was
-read with a doubled letter (7 characters), so it was refused and refreshed, never submitted.
-
-**The misses** are the letters mixed case makes ambiguous: `k`/`K`, `j`/`J`, `8`/`B`, `q`/`g`. A site with an
-unambiguous charset (no look-alikes, one case) reads better.
+**Real Vahan images** (`e2e/corpus/vahan`): 100 captchas from the public report, collected on 2026-09-26 and
+labelled by hand. A read is submitted **right**, submitted **wrong** (the site refuses it; a form post and a page
+load lost), or **refused** (refreshed for free, never submitted):
+
+| Settings | Right | Wrong | Refused |
+|---|---|---|---|
+| The site's charset, cross-check (the defaults otherwise) | 73 | 1 | 26 |
+| The site's charset, no cross-check | 78 | 6 | 16 |
+| `A-Za-z0-9`, no cross-check | 71 | 12 | 17 |
+
+- **Name the charset the site really uses.** In 600 labelled characters, 16 never appear: `0 I O` and the
+  lowercase letters that look like capitals or like other glyphs (`c i j k l m o p s v w x y z`). Allowing
+  them doubles the wrong reads: `1` read as `l`, `J` as `j`.
+- **Keep the cross-check.** It turns 5 of the 6 remaining wrong reads into refreshes. The one left is an image
+  whose last character is cut off by its edge. A captcha takes 1.35 reads per submitted code on average, and
+  1.01 posts per solved one.
+- **`minConfidence` barely matters.** The wrong reads are sure ones (90% and more). From 0 to 50 the threshold
+  only refuses right reads (75 right at 0, 73 at 30, 70 at 50), and catches none of the wrong ones once the
+  cross-check is on.
+- **Clipped images** (16 of the 100, the last character cut off by the image's edge) are refused or read right,
+  except that one.
+
+**The synthetic e2e corpus:** 6-character mixed-case codes drawn like the Vahan report's, but with every letter
+of both cases. Over 80 codes, with the cross-check, 75% are right, 16% refused, 9% wrong. The misses are the
+letters mixed case makes ambiguous (`j`/`J`, `s`/`S`, `y`/`Y`): both reads agree on the wrong case.
 
 Solving a site's captcha can break its terms of service. Read OpenCraw's [captcha guide](../../docs/recipes/captcha.md)
 first.

package/dist/index.esm.js

@@ -59,8 +59,13 @@ function expandRanges(list) {
   return characters;
 }
 
-const WHITE = 255;
+const WHITE$1 = 255;
 const BLACK = 0;
+/** PNG output for Tesseract, not for storage: no row filter search and light compression, many times faster to write. */
+const FAST_PNG = {
+  filterType: 0,
+  deflateLevel: 1
+};
 /**
  * Cleans a captcha image for OCR: grayscale, black ink on white (a threshold
  * picked by Otsu's method unless given, turned the right way round), an
@@ -85,7 +90,7 @@ function cleanImage(png, options = {}) {
   const inkShare = ink.reduce((sum, value) => sum + value, 0) / ink.length;
   if (options.invert === true || (options.invert ?? 'auto') === 'auto' && inkShare > 0.5) ink = ink.map(value => 1 - value);
   if (options.median === true) ink = medianOf(ink, width, height);
-  return PNG.sync.write(render(ink, width, height, padding));
+  return PNG.sync.write(render(ink, width, height, padding), FAST_PNG);
 }
 /**
  * The threshold that best splits the luminances in two groups (Otsu): the
@@ -125,7 +130,7 @@ function luminanceOf(rgba, pixels) {
     const offset = pixel * 4;
     const alpha = rgba[offset + 3] / 255;
     // A transparent pixel is the white page behind it.
-    const blend = channel => channel * alpha + WHITE * (1 - alpha);
+    const blend = channel => channel * alpha + WHITE$1 * (1 - alpha);
     const red = blend(rgba[offset]);
     const green = blend(rgba[offset + 1]);
     const blue = blend(rgba[offset + 2]);
@@ -158,7 +163,7 @@ function render(ink, width, height, padding) {
     width: outWidth,
     height: height + padding * 2
   });
-  out.data.fill(WHITE);
+  out.data.fill(WHITE$1);
   for (let y = 0; y < height; y += 1) {
     for (let x = 0; x < width; x += 1) {
       const start = ((y + padding) * outWidth + x + padding) * 4;
@@ -189,6 +194,62 @@ function upscale(luminance, width, height, scale) {
   return scaled;
 }
 
+const WHITE = 255;
+const INK_UNDER = 128;
+/**
+ * Pulls the glyphs of a cleaned image apart: each run of columns holding ink
+ * (a character, or characters that touch) is laid out again with `gap` white
+ * columns between runs. Tesseract reads a line with context and can bend a
+ * character to fit its neighbours (a `4` after lowercase letters read as
+ * `a`); spaced apart, each is read more on its own shape.
+ *
+ * Like reading a word letter by letter with a finger under each one.
+ *
+ * @param png - A cleaned image (black ink on white), as PNG bytes.
+ * @param gap - White columns before, between and after the runs.
+ * @returns The respaced image, as PNG bytes; the same height.
+ */
+function respaceGlyphs(png, gap) {
+  const image = PNG.sync.read(png);
+  const runs = inkRuns(image);
+  const width = runs.reduce((total, [start, end]) => total + (end - start) + gap, gap);
+  const out = new PNG({
+    width,
+    height: image.height
+  });
+  out.data.fill(WHITE);
+  let at = gap;
+  for (const [start, end] of runs) {
+    for (let y = 0; y < image.height; y += 1) {
+      const from = (y * image.width + start) * 4;
+      image.data.copy(out.data, (y * width + at) * 4, from, from + (end - start) * 4);
+    }
+    at += end - start + gap;
+  }
+  return PNG.sync.write(out, FAST_PNG);
+}
+/** The column ranges `[start, end)` that hold ink, left to right. */
+function inkRuns(image) {
+  const runs = [];
+  let start = -1;
+  for (let x = 0; x < image.width; x += 1) {
+    const ink = hasInk(image, x);
+    if (ink && start < 0) start = x;
+    if (!ink && start >= 0) {
+      runs.push([start, x]);
+      start = -1;
+    }
+  }
+  if (start >= 0) runs.push([start, image.width]);
+  return runs;
+}
+function hasInk(image, x) {
+  for (let y = 0; y < image.height; y += 1) {
+    if (image.data[(y * image.width + x) * 4] < INK_UNDER) return true;
+  }
+  return false;
+}
+
 /** Letters whose small and capital forms have the same shape: only their height tells them apart. */
 const SAME_SHAPE = new Set('cosuvwxz');
 /** Letters whose small form has a tail under the line, and whose capital does not. */
@@ -353,8 +414,10 @@ function symbolsOf(blocks) {
 }
 
 const DEFAULT_REFRESHES = 5;
-const DEFAULT_MIN_CONFIDENCE = 50;
+const DEFAULT_MIN_CONFIDENCE = 30;
 const DEFAULT_TIMEOUT_MS = 60_000;
+/** White columns (of the cleaned image) between glyphs for the cross-check read. */
+const CROSS_CHECK_GAP = 10;
 /** An image counts as settled once its `src` stayed the same this long. */
 const SETTLE_MS = 300;
 const SETTLE_LIMIT_MS = 5000;
@@ -393,22 +456,53 @@ function tesseractReader(options = {}) {
       context?.log('warn', `audit failed: ${error instanceof Error ? error.message : String(error)}`);
     }
   };
-  const read = async png => {
-    const started = Date.now();
-    const cleaned = cleanImage(png, options.preprocess);
+  const crossCheck = options.crossCheck ?? true;
+  /** One Tesseract read of a cleaned image, judged. */
+  const readOnce = async cleaned => {
     const {
       raw,
       symbols: read
     } = await engine.read(cleaned);
     // Tesseract sees one line with no size reference: the case of same-shape letters is put right by their size.
     const symbols = caseSensitive ? fixLetterCase(read, characters) : read;
-    const judged = judgeRead(caseSensitive ? symbols.map(symbol => symbol.text).join('') : raw, symbols, rules);
     return {
-      ...judged,
+      raw,
+      symbols,
+      judged: judgeRead(caseSensitive ? symbols.map(symbol => symbol.text).join('') : raw, symbols, rules)
+    };
+  };
+  const read = async png => {
+    const started = Date.now();
+    const cleaned = cleanImage(png, options.preprocess);
+    const {
+      raw,
+      symbols,
+      judged
+    } = await readOnce(cleaned);
+    const done = {
       raw,
       symbols,
       image: png,
-      cleaned,
+      cleaned
+    };
+    if (!crossCheck || judged.problem !== undefined) return {
+      ...judged,
+      ...done,
+      durationMs: Date.now() - started
+    };
+    const {
+      judged: second
+    } = await readOnce(respaceGlyphs(cleaned, CROSS_CHECK_GAP));
+    const confidence = Math.min(judged.confidence, second.confidence);
+    const problem = second.text === judged.text ? second.problem : `a second read, with the characters spaced apart, gave "${second.text}"`;
+    return {
+      text: judged.text,
+      confidence,
+      second: second.text,
+      ...(problem !== undefined && {
+        problem
+      }),
+      ...done,
       durationMs: Date.now() - started
     };
   };

package/dist/src/image-cleanup/clean-image.algorithm.d.ts

@@ -11,6 +11,11 @@ export interface CleanupOptions {
     /** White margin around the text, in output pixels: Tesseract misses glyphs touching the edge. Default 10. */
     padding?: number;
 }
+/** PNG output for Tesseract, not for storage: no row filter search and light compression, many times faster to write. */
+export declare const FAST_PNG: {
+    filterType: number;
+    deflateLevel: number;
+};
 /**
  * Cleans a captcha image for OCR: grayscale, black ink on white (a threshold
  * picked by Otsu's method unless given, turned the right way round), an

package/dist/src/image-cleanup/index.d.ts

@@ -1,3 +1,4 @@
 export { cleanImage, otsuThreshold } from './clean-image.algorithm.js';
 export type { CleanupOptions } from './clean-image.algorithm.js';
+export { respaceGlyphs } from './respace-glyphs.algorithm.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/image-cleanup/respace-glyphs.algorithm.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pulls the glyphs of a cleaned image apart: each run of columns holding ink
+ * (a character, or characters that touch) is laid out again with `gap` white
+ * columns between runs. Tesseract reads a line with context and can bend a
+ * character to fit its neighbours (a `4` after lowercase letters read as
+ * `a`); spaced apart, each is read more on its own shape.
+ *
+ * Like reading a word letter by letter with a finger under each one.
+ *
+ * @param png - A cleaned image (black ink on white), as PNG bytes.
+ * @param gap - White columns before, between and after the runs.
+ * @returns The respaced image, as PNG bytes; the same height.
+ */
+export declare function respaceGlyphs(png: Buffer, gap: number): Buffer;
+//# sourceMappingURL=respace-glyphs.algorithm.d.ts.map

package/dist/src/reader/reader.contract.d.ts

@@ -58,7 +58,9 @@ export interface ImageRead {
     /** The least sure character's confidence (0–100): whole-word confidence is too noisy on six loose characters. */
     confidence: number;
     symbols: ReadSymbol[];
-    /** Why the read is not good enough to submit (a wrong length, a low confidence), when it is not. */
+    /** The cross-check's read, with the characters spaced apart, when one was made (the first read passed its checks). */
+    second?: string;
+    /** Why the read is not good enough to submit (a wrong length, a low confidence, a cross-check that disagreed), when it is not. */
     problem?: string;
     /** The image as captured, and as Tesseract saw it after cleanup (PNG). */
     image: Buffer;
@@ -85,10 +87,17 @@ export interface TesseractReaderOptions {
     length?: number | [number, number];
     /** Whether `a` and `A` differ. Default `false`: each letter allows its other case too. */
     caseSensitive?: boolean;
-    /** The least confidence (0–100) every character must have. Default 50. */
+    /** The least confidence (0–100) every character must have. Default 30. */
     minConfidence?: number;
     /** Reads (after refreshing the image) before an attempt gives up. Default 5. */
     refreshes?: number;
+    /**
+     * Reads the code a second time with its characters spaced apart, and submits only when both reads agree.
+     * Tesseract reads a line with context and can bend a character to fit its neighbours (a `4` after lowercase
+     * letters read as `a`); read apart, it rarely makes the same mistake. Default `true`: on 100 real captchas it cut
+     * wrong submissions from 6 to 1, for a few more (free) refreshes and a second read of each passing image.
+     */
+    crossCheck?: boolean;
     /** Image cleanup before OCR. */
     preprocess?: CleanupOptions;
     /** Tesseract's page segmentation mode: 7 one line (default), 8 one word, 13 a raw line. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/captcha-tesseract",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",