@albex/ocr 0.2.0

package/README.md

@@ -0,0 +1,180 @@
+# `@albex/ocr`
+
+Optional OCR module for [Albex](https://www.npmjs.com/package/albex) powered by
+[Tesseract.js](https://github.com/naptha/tesseract.js). Lazy at every level:
+the package is opt-in, the Tesseract library is dynamic-imported on first use,
+language models are downloaded on demand and cached forever in IndexedDB.
+
+## Install
+
+```bash
+npm install @albex/ocr
+```
+
+This package has a peer dependency on `albex@^0.2.0`.
+
+## Quick start
+
+```ts
+import { AlbexEngine } from 'albex';
+import { enableOcr }   from '@albex/ocr';
+
+const engine = new AlbexEngine();
+await engine.init();
+
+const ocr = enableOcr(engine);
+
+// engine now exposes ocrImage()
+const blob: Blob = await fetch('/scan.png').then(r => r.blob());
+const { text, confidence } = await engine.ocrImage(blob);
+
+console.log(`OCR: ${text} (confidence ${confidence}%)`);
+```
+
+## Scanned PDFs
+
+`@albex/ocr` also handles scanned (image-only) PDFs transparently. After
+`enableOcr(engine)`, any PDF whose text layer is empty will be routed
+through OCR automatically:
+
+```ts
+import { AlbexEngine } from 'albex';
+import { enableOcr }   from '@albex/ocr';
+
+const engine = new AlbexEngine();
+await engine.init();
+enableOcr(engine);
+
+// Digital PDF → text is extracted directly.
+// Scanned PDF  → embedded JPEG/JPEG2000 pages are OCR'd.
+await engine.indexFile(pdfFile);
+
+const hits = engine.search('contract');
+```
+
+The work is split between the PDF WebAssembly module and Tesseract.js:
+
+1. `albex_pdf.wasm` parses the PDF and detects whether each page has
+   extractable text.
+2. For pages that don't, the same module copies out the embedded image
+   stream — exactly as it lives inside the PDF, no decoding in Rust.
+3. The browser decodes the image via `<img>` / `createImageBitmap` and
+   Tesseract.js runs OCR on the pixels.
+
+**What's supported.** Pages where the embedded image is a JPEG
+(`/DCTDecode`) or a JPEG2000 (`/JPXDecode`). Modern scanners — Adobe
+Acrobat, ABBYY FineReader, mobile scan apps — ship JPEG by default, so
+this covers the overwhelming majority of real-world scanned PDFs.
+
+**What's not (yet).** Pages whose image uses `/FlateDecode`,
+`/CCITTFaxDecode` or `/JBIG2Decode`. Extracting those would require a
+PNG/TIFF encoder inside the Rust crate (~+2 MB to `albex_pdf.wasm`), and
+in practice they show up in ~5 % of scanned PDFs. If you hit one, the page
+contributes zero chunks and the document is still registered — search
+won't match those pages, but everything else keeps working. A fallback
+that uses `pdfjs-dist` to render the page is on the backlog.
+
+## Languages
+
+Six languages are pre-supported with automatic worker creation:
+
+| Lang code | Language   |
+|-----------|------------|
+| `eng`     | English    |
+| `spa`     | Spanish    |
+| `fra`     | French     |
+| `deu`     | German     |
+| `ita`     | Italian    |
+| `por`     | Portuguese |
+
+Other Tesseract languages (~100 total) work but must be requested explicitly:
+
+```ts
+await engine.ocrImage(blob, { lang: 'rus' });
+```
+
+## Language auto-detection
+
+`@albex/ocr` exports a lightweight detector for the six pre-supported
+languages. Use it when you have a sample of known-good text (e.g. a previous
+OCR pass) and want to pick the right language for subsequent images:
+
+```ts
+import { detectLanguageOr } from '@albex/ocr';
+
+const sample = "Le contrat établit les clauses de l'accord";
+const lang   = detectLanguageOr(sample);   // → 'fra'
+
+await engine.ocrImage(image, { lang });
+```
+
+The detector is a ~4 KB blend of distinctive character checks and stop-word
+matching. It is intentionally NOT a robust language ID model — when in doubt
+it falls back to the supplied default (typically `'eng'`).
+
+## Options
+
+```ts
+enableOcr(engine, {
+  languages:        ['eng', 'spa', 'fra'],   // allowlist (default: all 6)
+  defaultLanguage:  'eng',                   // when detection abstains
+  preload:          ['eng'],                 // warm models eagerly
+  idleTimeoutMs:    5 * 60_000,              // evict inactive workers
+  langPath:         'https://my.cdn/lang/',  // override traineddata source
+});
+```
+
+## Lifecycle
+
+The handle returned by `enableOcr` exposes diagnostic and teardown methods:
+
+```ts
+const ocr = enableOcr(engine);
+
+await ocr.preload(['eng', 'spa']);       // wait for warming to finish
+console.log(ocr.loadedLanguages());      // → ['eng', 'spa']
+
+await ocr.dispose();                     // terminate all workers
+                                         // engine.ocrImage is removed
+```
+
+The handle is also a TC39 disposable, so you can `using ocr = enableOcr(engine)`
+in environments that support it.
+
+## Performance
+
+Tesseract.js on a typical 1024×1024 scanned page in 2026:
+
+| Variant                | Per page CPU | Per page WebGPU* |
+|------------------------|-------------:|-----------------:|
+| `_fast` models (this)  | 1–3 s        | 0.5–1.5 s        |
+| `_best` models         | 3–8 s        | 1.5–3 s          |
+
+*WebGPU is experimental in Tesseract.js v5.1+. Enabled automatically when
+available.
+
+The "fast" models trade ~5 % char-level accuracy for 4–6× smaller size and
+similar speedup. For Albex, that 5 % is invisible: the fuzzy Bitap matcher
+already tolerates up to 3 character errors per token, and the accent-fold
+plus lowercase normalisation absorb the other typical OCR mistakes.
+
+## Bundle impact
+
+Zero. Until `enableOcr()` is invoked at runtime, nothing in this package
+ships in your initial bundle. The Tesseract.js library, its WASM core and
+language models are all downloaded on demand and cached in IndexedDB.
+
+Typical download path for a user that drags one Spanish scanned PDF:
+
+| Step                                | Cost        | When               |
+|-------------------------------------|-------------|--------------------|
+| Initial app load                    | 0 bytes     | (no OCR yet)       |
+| First call to `ocrImage`            | ~3.5 MB     | Tesseract runtime  |
+| ↳ First Spanish recognise           | ~1.8 MB     | spa_fast model     |
+| Subsequent Spanish recognises       | 0 bytes     | (cached)           |
+| Subsequent visits to the same origin| 0 bytes     | (IndexedDB cache)  |
+
+## License
+
+MIT. Same as [Tesseract.js](https://github.com/naptha/tesseract.js) and
+[albex](https://www.npmjs.com/package/albex).

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Errors thrown by `@albex/ocr`. Mirrors the AlbexError hierarchy of the
+ * main package: subclass of `Error`, exposes a `kind` discriminator that
+ * survives `structuredClone` across worker boundaries.
+ */
+export declare class AlbexOcrError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+}
+export declare class AlbexOcrInitError extends AlbexOcrError {
+    constructor(message: string);
+}
+export declare class AlbexOcrLanguageError extends AlbexOcrError {
+    readonly lang: string;
+    constructor(lang: string, message: string);
+}
+export declare class AlbexOcrRecognitionError extends AlbexOcrError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,qBAAa,iBAAkB,SAAQ,aAAa;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Errors thrown by `@albex/ocr`. Mirrors the AlbexError hierarchy of the
+ * main package: subclass of `Error`, exposes a `kind` discriminator that
+ * survives `structuredClone` across worker boundaries.
+ */
+export class AlbexOcrError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'AlbexOcrError';
+        this.kind = kind;
+    }
+}
+export class AlbexOcrInitError extends AlbexOcrError {
+    constructor(message) {
+        super('ocr_init', message);
+        this.name = 'AlbexOcrInitError';
+    }
+}
+export class AlbexOcrLanguageError extends AlbexOcrError {
+    lang;
+    constructor(lang, message) {
+        super('ocr_language', message);
+        this.name = 'AlbexOcrLanguageError';
+        this.lang = lang;
+    }
+}
+export class AlbexOcrRecognitionError extends AlbexOcrError {
+    constructor(message) {
+        super('ocr_recognition', message);
+        this.name = 'AlbexOcrRecognitionError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACzD,YAAY,OAAe;QACzB,KAAK,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@albex/ocr` — OCR module for Albex.
+ *
+ * Drop-in OCR for Albex powered by Tesseract.js. Lazy loaded at every level:
+ * the package itself is opt-in, the Tesseract.js library is dynamic-imported
+ * on first use, language models are downloaded on demand and cached forever
+ * in IndexedDB.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { AlbexEngine } from 'albex';
+ * import { enableOcr }   from '@albex/ocr';
+ *
+ * const engine = new AlbexEngine();
+ * await engine.init();
+ *
+ * const ocr = enableOcr(engine);
+ *
+ * const { text } = await engine.ocrImage(myImageBlob);
+ * console.log(text);
+ * ```
+ */
+export { enableOcr, detectLanguage, detectLanguageOr, scoreLanguages, SUPPORTED_LANGS, AlbexOcrError, AlbexOcrInitError, AlbexOcrLanguageError, AlbexOcrRecognitionError, } from './orchestrator.js';
+export type { OcrHandle, OcrOptions, OcrRecognizeOptions, OcrCapableEngine, Lang, RecognitionResult, ImageLike, } from './orchestrator.js';
+export { OcrWorkerPool } from './ocr-worker.js';
+export type { OcrWorkerOptions } from './ocr-worker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,IAAI,EACJ,iBAAiB,EACjB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * `@albex/ocr` — OCR module for Albex.
+ *
+ * Drop-in OCR for Albex powered by Tesseract.js. Lazy loaded at every level:
+ * the package itself is opt-in, the Tesseract.js library is dynamic-imported
+ * on first use, language models are downloaded on demand and cached forever
+ * in IndexedDB.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { AlbexEngine } from 'albex';
+ * import { enableOcr }   from '@albex/ocr';
+ *
+ * const engine = new AlbexEngine();
+ * await engine.init();
+ *
+ * const ocr = enableOcr(engine);
+ *
+ * const { text } = await engine.ocrImage(myImageBlob);
+ * console.log(text);
+ * ```
+ */
+export { enableOcr, detectLanguage, detectLanguageOr, scoreLanguages, SUPPORTED_LANGS, AlbexOcrError, AlbexOcrInitError, AlbexOcrLanguageError, AlbexOcrRecognitionError, } from './orchestrator.js';
+export { OcrWorkerPool } from './ocr-worker.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/language-detector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lightweight language detection for the 6 pre-supported OCR languages.
+ *
+ * The signal is a combination of:
+ *   1. Distinctive single characters (`ñ`, `ç`, `ß`, …).
+ *   2. The most common stop words of each language, scored by frequency.
+ *
+ * The detector is meant to be called on a SHORT sample of source text — a
+ * paragraph or two from a known-good area of the document, or a previous
+ * OCR pass of the first page. It is NOT a robust language ID model; the
+ * threshold of confidence below which we fall back to `eng` is intentional.
+ *
+ * Total weight in the bundle: ~4 KB minified once the rest of the package
+ * is tree-shaken alongside it.
+ */
+export type Lang = 'eng' | 'spa' | 'fra' | 'deu' | 'ita' | 'por';
+export declare const SUPPORTED_LANGS: readonly Lang[];
+/**
+ * Score how likely a sample of text is in each candidate language.
+ *
+ * Returns scores normalised so the top language is always > 0. Use
+ * `detectLanguage` for the simple "which one?" answer.
+ */
+export declare function scoreLanguages(text: string): Record<Lang, number>;
+/**
+ * Pick the most likely language. Returns `null` when no signal is strong
+ * enough — the caller should fall back to a configured default (usually
+ * `eng`).
+ *
+ * `minScore` is the threshold below which we abstain. Default 6 — empirical
+ * from testing on short samples (<200 chars) of each language.
+ */
+export declare function detectLanguage(text: string, minScore?: number): Lang | null;
+/**
+ * Convenience: detect with a fallback. The default fallback is `eng`,
+ * which is also the safest universal choice for technical / mixed corpora.
+ */
+export declare function detectLanguageOr(text: string, fallback?: Lang, minScore?: number): Lang;
+//# sourceMappingURL=language-detector.d.ts.map

package/dist/language-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-detector.d.ts","sourceRoot":"","sources":["../src/language-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEjE,eAAO,MAAM,eAAe,EAAE,SAAS,IAAI,EAA+C,CAAC;AA6C3F;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CA4BjE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,IAAI,GAAG,IAAI,CAatE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,IAAY,EAAE,QAAQ,SAAI,GAAG,IAAI,CAEzF"}

package/dist/language-detector.js

@@ -0,0 +1,111 @@
+/**
+ * Lightweight language detection for the 6 pre-supported OCR languages.
+ *
+ * The signal is a combination of:
+ *   1. Distinctive single characters (`ñ`, `ç`, `ß`, …).
+ *   2. The most common stop words of each language, scored by frequency.
+ *
+ * The detector is meant to be called on a SHORT sample of source text — a
+ * paragraph or two from a known-good area of the document, or a previous
+ * OCR pass of the first page. It is NOT a robust language ID model; the
+ * threshold of confidence below which we fall back to `eng` is intentional.
+ *
+ * Total weight in the bundle: ~4 KB minified once the rest of the package
+ * is tree-shaken alongside it.
+ */
+export const SUPPORTED_LANGS = ['eng', 'spa', 'fra', 'deu', 'ita', 'por'];
+/**
+ * One profile per language. Stop words come from the OPUS-100 / Wikipedia
+ * frequency tables; the top 12 of each language cover ~25-30 % of any
+ * substantial text. Distinctive characters are conservative — listed only
+ * when they appear in that language and almost nowhere else among our six.
+ */
+const PROFILES = {
+    eng: {
+        chars: [], // English shares its alphabet with everyone else in our set.
+        stopWords: ['the', 'of', 'and', 'to', 'in', 'a', 'is', 'that', 'for', 'it', 'with', 'as'],
+    },
+    spa: {
+        chars: ['ñ', '¿', '¡'],
+        stopWords: ['de', 'la', 'que', 'el', 'en', 'y', 'a', 'los', 'se', 'del', 'las', 'por'],
+    },
+    fra: {
+        chars: ['ç', 'œ', 'à', 'â', 'ê', 'ô', 'û'],
+        stopWords: ['de', 'la', 'le', 'et', 'les', 'des', 'un', 'une', 'que', 'il', 'au', 'aux'],
+    },
+    deu: {
+        chars: ['ß', 'ü', 'ö', 'ä'],
+        stopWords: ['die', 'der', 'und', 'in', 'den', 'von', 'zu', 'das', 'mit', 'sich', 'des', 'auf'],
+    },
+    ita: {
+        chars: [], // No unique distinctive chars vs spa/por.
+        stopWords: ['di', 'la', 'il', 'e', 'che', 'un', 'del', 'le', 'per', 'una', 'gli', 'sono'],
+    },
+    por: {
+        chars: ['ã', 'õ'],
+        stopWords: ['de', 'a', 'o', 'que', 'e', 'do', 'da', 'em', 'um', 'para', 'os', 'com'],
+    },
+};
+const CHAR_WEIGHT = 8;
+const STOP_WEIGHT = 4;
+/**
+ * Score how likely a sample of text is in each candidate language.
+ *
+ * Returns scores normalised so the top language is always > 0. Use
+ * `detectLanguage` for the simple "which one?" answer.
+ */
+export function scoreLanguages(text) {
+    const lower = text.toLowerCase();
+    // Tokenise into words once — used by stop word scoring.
+    // Accepts UTF-8 letters and digits; everything else is a separator.
+    const words = lower.match(/[\p{L}\p{N}']+/gu) ?? [];
+    const wordSet = new Set(words);
+    const scores = { eng: 0, spa: 0, fra: 0, deu: 0, ita: 0, por: 0 };
+    for (const lang of SUPPORTED_LANGS) {
+        const profile = PROFILES[lang];
+        // Distinctive char score.
+        for (const c of profile.chars) {
+            if (lower.includes(c))
+                scores[lang] += CHAR_WEIGHT;
+        }
+        // Stop word score — top words count more.
+        for (let i = 0; i < profile.stopWords.length; i++) {
+            const word = profile.stopWords[i];
+            if (wordSet.has(word)) {
+                // First word in the list = highest weight; decays linearly.
+                scores[lang] += STOP_WEIGHT * (1 - i / profile.stopWords.length);
+            }
+        }
+    }
+    return scores;
+}
+/**
+ * Pick the most likely language. Returns `null` when no signal is strong
+ * enough — the caller should fall back to a configured default (usually
+ * `eng`).
+ *
+ * `minScore` is the threshold below which we abstain. Default 6 — empirical
+ * from testing on short samples (<200 chars) of each language.
+ */
+export function detectLanguage(text, minScore = 6) {
+    if (text.length < 20)
+        return null; // Nothing to learn from.
+    const scores = scoreLanguages(text);
+    let best = null;
+    let bestScore = -1;
+    for (const lang of SUPPORTED_LANGS) {
+        if (scores[lang] > bestScore) {
+            bestScore = scores[lang];
+            best = lang;
+        }
+    }
+    return bestScore >= minScore ? best : null;
+}
+/**
+ * Convenience: detect with a fallback. The default fallback is `eng`,
+ * which is also the safest universal choice for technical / mixed corpora.
+ */
+export function detectLanguageOr(text, fallback = 'eng', minScore = 6) {
+    return detectLanguage(text, minScore) ?? fallback;
+}
+//# sourceMappingURL=language-detector.js.map

package/dist/language-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-detector.js","sourceRoot":"","sources":["../src/language-detector.ts"],"names":[],"mappings":"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"}

package/dist/ocr-worker.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Wrapper around Tesseract.js.
+ *
+ * Responsibilities:
+ *   1. Lazy-load the Tesseract.js library on first use (dynamic import).
+ *   2. Maintain a per-language `Worker` instance, created on demand.
+ *   3. Auto-terminate idle workers after a configurable timeout to release
+ *      the LSTM model from memory (each Tesseract worker holds 2-5 MB).
+ *   4. Expose a Promise-based `recognize(image, lang)` that returns text +
+ *      confidence in a stable shape.
+ *
+ * Why one worker per language: Tesseract.js workers are tied to the language
+ * model they were initialised with. Switching languages on the same worker
+ * triggers a slow reload of the LSTM. Maintaining N workers — one per
+ * language ever used — keeps each recognise call fast at the cost of slightly
+ * more memory, which the idle eviction then claws back.
+ */
+import type { Lang } from './language-detector.js';
+/**
+ * Anything Tesseract.js can accept as input. We narrow to what an Albex
+ * consumer is likely to hand us (Blob, ArrayBuffer, Uint8Array, an HTML
+ * image element). The Tesseract.js source itself does the discrimination.
+ */
+export type ImageLike = Blob | ArrayBuffer | Uint8Array | string | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas;
+export interface RecognitionResult {
+    /** Raw OCR output. May contain newlines for paragraphs / lines. */
+    text: string;
+    /** 0-100 confidence reported by Tesseract for the page. */
+    confidence: number;
+    /** Wall-clock time spent on this recognition. */
+    timeMs: number;
+}
+export interface OcrWorkerOptions {
+    /**
+     * Milliseconds of inactivity after which an idle Tesseract worker is
+     * terminated and its language model released. Default: 5 minutes.
+     * Set 0 to disable eviction (worker stays for the lifetime of the page).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Override the `tessdata_fast` mirror. Defaults to the official Tesseract.js
+     * jsDelivr mirror, which is what `tesseract.js` ships with anyway.
+     */
+    langPath?: string;
+}
+export declare class OcrWorkerPool {
+    private _workers;
+    private _evictionTimer;
+    private readonly _idleTimeoutMs;
+    private readonly _langPath;
+    constructor(opts?: OcrWorkerOptions);
+    /**
+     * Run OCR on a single image. Spawns the appropriate language worker on
+     * first use and caches it; subsequent calls for the same language reuse it.
+     */
+    recognize(image: ImageLike, lang: Lang): Promise<RecognitionResult>;
+    /**
+     * Names of languages currently loaded in memory. Useful for diagnostics
+     * and for the demo's runtime panel.
+     */
+    loadedLanguages(): Lang[];
+    /**
+     * Tear down all workers immediately. Called by orchestrator dispose.
+     */
+    dispose(): Promise<void>;
+    /** TC39 explicit-resource-management alias. Fires `dispose()` async. */
+    [Symbol.dispose](): void;
+    private _getOrCreate;
+    private _sweepIdle;
+}
+//# sourceMappingURL=ocr-worker.d.ts.map

package/dist/ocr-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ocr-worker.d.ts","sourceRoot":"","sources":["../src/ocr-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAqBnD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,WAAW,GACX,UAAU,GACV,MAAM,GACN,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAqCD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;gBAEnC,IAAI,GAAE,gBAAqB;IAiBvC;;;OAGG;IACG,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkBzE;;;OAGG;IACH,eAAe,IAAI,IAAI,EAAE;IAIzB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,wEAAwE;IACxE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;YAMV,YAAY;YA2BZ,UAAU;CAWzB"}