@albex/ocr 0.2.0

package/dist/ocr-worker.js

@@ -0,0 +1,146 @@
+/**
+ * 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 { AlbexOcrInitError, AlbexOcrLanguageError, AlbexOcrRecognitionError, } from './errors.js';
+/**
+ * Single global Tesseract module reference. The dynamic import is shared
+ * across every OCR call once it resolves.
+ */
+let tesseractPromise = null;
+function loadTesseract() {
+    if (tesseractPromise)
+        return tesseractPromise;
+    tesseractPromise = (async () => {
+        try {
+            // The bundler resolves this to the `tesseract.js` ESM entry. Tesseract
+            // internally pulls its own WASM core and worker script lazily, so we
+            // don't pay for them until createWorker is called.
+            const mod = (await import('tesseract.js'));
+            if (typeof mod.createWorker !== 'function') {
+                throw new Error('tesseract.js: createWorker export missing');
+            }
+            return mod;
+        }
+        catch (e) {
+            tesseractPromise = null; // allow retry
+            throw new AlbexOcrInitError(`Failed to load tesseract.js: ${e.message}`);
+        }
+    })();
+    return tesseractPromise;
+}
+export class OcrWorkerPool {
+    _workers = new Map();
+    _evictionTimer = null;
+    _idleTimeoutMs;
+    _langPath;
+    constructor(opts = {}) {
+        this._idleTimeoutMs = opts.idleTimeoutMs ?? 5 * 60_000;
+        this._langPath = opts.langPath;
+        if (this._idleTimeoutMs > 0) {
+            // Sweep every minute. We don't need finer granularity for "did this
+            // worker idle past the threshold?".
+            this._evictionTimer = setInterval(() => { void this._sweepIdle(); }, Math.min(60_000, this._idleTimeoutMs));
+            // Don't keep the event loop alive just because we have a timer.
+            // (Browsers don't have unref; Node does.)
+            const t = this._evictionTimer;
+            t.unref?.();
+        }
+    }
+    /**
+     * 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.
+     */
+    async recognize(image, lang) {
+        const entry = await this._getOrCreate(lang);
+        entry.pending++;
+        const t0 = performance.now();
+        try {
+            const { data } = await entry.worker.recognize(image);
+            const elapsed = performance.now() - t0;
+            entry.lastUsedAt = Date.now();
+            return { text: data.text, confidence: data.confidence, timeMs: elapsed };
+        }
+        catch (e) {
+            throw new AlbexOcrRecognitionError(`OCR failed for language=${lang}: ${e.message}`);
+        }
+        finally {
+            entry.pending--;
+        }
+    }
+    /**
+     * Names of languages currently loaded in memory. Useful for diagnostics
+     * and for the demo's runtime panel.
+     */
+    loadedLanguages() {
+        return [...this._workers.keys()];
+    }
+    /**
+     * Tear down all workers immediately. Called by orchestrator dispose.
+     */
+    async dispose() {
+        if (this._evictionTimer) {
+            clearInterval(this._evictionTimer);
+            this._evictionTimer = null;
+        }
+        const all = [...this._workers.values()];
+        this._workers.clear();
+        await Promise.allSettled(all.map(e => e.worker.terminate()));
+    }
+    /** TC39 explicit-resource-management alias. Fires `dispose()` async. */
+    [Symbol.dispose]() {
+        void this.dispose();
+    }
+    // ── internals ─────────────────────────────────────────────────────────
+    async _getOrCreate(lang) {
+        const existing = this._workers.get(lang);
+        if (existing)
+            return existing;
+        const tess = await loadTesseract();
+        let worker;
+        try {
+            // Tesseract.js v5+ createWorker(lang, oem, opts). `oem: 1` = LSTM only
+            // (the fast modern path, faster than the legacy Cube engine).
+            const opts = this._langPath ? { langPath: this._langPath } : undefined;
+            worker = await tess.createWorker(lang, 1, opts);
+        }
+        catch (e) {
+            throw new AlbexOcrLanguageError(lang, `Failed to load language model "${lang}": ${e.message}`);
+        }
+        const entry = {
+            worker,
+            lang,
+            lastUsedAt: Date.now(),
+            pending: 0,
+        };
+        this._workers.set(lang, entry);
+        return entry;
+    }
+    async _sweepIdle() {
+        const now = Date.now();
+        const victims = [];
+        for (const [lang, entry] of this._workers) {
+            if (entry.pending > 0)
+                continue;
+            if (now - entry.lastUsedAt < this._idleTimeoutMs)
+                continue;
+            this._workers.delete(lang);
+            victims.push(entry);
+        }
+        await Promise.allSettled(victims.map(v => v.worker.terminate()));
+    }
+}
+//# sourceMappingURL=ocr-worker.js.map

package/dist/ocr-worker.js.map

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

package/dist/orchestrator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Public surface of `@albex/ocr`.
+ *
+ * The orchestrator wires an `OcrWorkerPool` to an `AlbexEngine` instance.
+ * After `enableOcr(engine)`:
+ *
+ *   - `engine.ocrImage(blob)` becomes available and returns recognised text.
+ *   - The text can be indexed manually with `engine.indexText(name, text)`
+ *     if such a primitive is exposed by the host (future addition).
+ *
+ * The returned `OcrHandle` lets the caller probe state, query loaded
+ * languages, force pre-load of specific languages, or shut down.
+ */
+import type { ImageLike, RecognitionResult } from './ocr-worker.js';
+import type { Lang } from './language-detector.js';
+/**
+ * The subset of `AlbexEngine` we need. Kept minimal so this package's only
+ * peer dependency on `albex` is a type contract.
+ */
+export interface OcrCapableEngine {
+    /** Storage slot where the orchestrator parks its public ocrImage method. */
+    ocrImage?: (image: ImageLike, opts?: OcrRecognizeOptions) => Promise<RecognitionResult>;
+    /** Structural slot the engine reads to decide whether to invoke OCR on
+     * embedded images of PDFs that ALSO have vector text. Set by `enableOcr`
+     * when the `alwaysExtractEmbeddedImages` option is true. */
+    ocrConfig?: {
+        alwaysExtractEmbeddedImages?: boolean;
+    };
+}
+export interface OcrOptions {
+    /**
+     * Languages to make available for auto-detection. Order matters only
+     * in tie-breaking. Default: all 6 supported languages.
+     */
+    languages?: readonly Lang[];
+    /**
+     * Default language when detection cannot decide (very short text, no
+     * distinctive characters). Default: `eng`.
+     */
+    defaultLanguage?: Lang;
+    /**
+     * Eagerly load these languages on `enableOcr` instead of waiting for
+     * the first call that needs them. Useful when you know the corpus
+     * language ahead of time and want a warm engine.
+     */
+    preload?: readonly Lang[];
+    /**
+     * Milliseconds of inactivity after which idle Tesseract workers are
+     * terminated and their language models released. Default: 5 minutes.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Override the location from which `<lang>_fast.traineddata` is fetched.
+     * Defaults to the jsDelivr mirror Tesseract.js uses internally.
+     */
+    langPath?: string;
+    /**
+     * Hybrid PDF mode. When `true`, the engine OCRs embedded images of
+     * EVERY PDF, not just PDFs that have no extractable vector text.
+     * Useful for documents that mix native text with scanned annexes,
+     * stamps, signatures or diagrams with text labels.
+     *
+     * Cost: 1–3 s of OCR per qualifying image (only images larger than
+     * 200×200 are sent to Tesseract; logos, scanner-corner marks and
+     * signature glyphs are skipped server-side in Rust).
+     *
+     * Default: `false`. Keep it off unless your corpus is known to
+     * contain hybrid PDFs.
+     */
+    alwaysExtractEmbeddedImages?: boolean;
+}
+export interface OcrRecognizeOptions {
+    /**
+     * Force a specific language. When omitted, the orchestrator attempts to
+     * detect it from the first run's output (if recoverable) and otherwise
+     * falls back to `defaultLanguage`.
+     */
+    lang?: Lang;
+    /**
+     * Hint of expected language for the first-pass detection. Useful when
+     * you know the doc is e.g. Spanish but don't want to lock it.
+     */
+    hint?: Lang;
+}
+export interface OcrHandle {
+    /** Pre-load the language models for the listed languages. */
+    preload(langs: readonly Lang[]): Promise<void>;
+    /** Currently loaded (in-memory) languages. */
+    loadedLanguages(): Lang[];
+    /** Tear down all workers and unhook from the engine. */
+    dispose(): Promise<void>;
+}
+/**
+ * Hook OCR into an Albex engine. Returns a handle that lets the caller
+ * preload languages, inspect state, and dispose cleanly.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { AlbexEngine } from 'albex';
+ * import { enableOcr } from '@albex/ocr';
+ *
+ * const engine = new AlbexEngine();
+ * await engine.init();
+ *
+ * const ocr = enableOcr(engine, { preload: ['eng', 'spa'] });
+ *
+ * const blob: Blob = await fetch('/scan.png').then(r => r.blob());
+ * const { text } = await engine.ocrImage(blob);
+ * ```
+ */
+export declare function enableOcr<T extends OcrCapableEngine>(engine: T, opts?: OcrOptions): OcrHandle;
+export { detectLanguage, detectLanguageOr, scoreLanguages, SUPPORTED_LANGS } from './language-detector.js';
+export type { Lang } from './language-detector.js';
+export type { RecognitionResult, ImageLike } from './ocr-worker.js';
+export { AlbexOcrError, AlbexOcrInitError, AlbexOcrLanguageError, AlbexOcrRecognitionError, } from './errors.js';
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAGnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxF;;gEAE4D;IAC5D,SAAS,CAAC,EAAE;QAAE,2BAA2B,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACvD;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,OAAO,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,8CAA8C;IAC9C,eAAe,IAAI,IAAI,EAAE,CAAC;IAC1B,wDAAwD;IACxD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,gBAAgB,EAClD,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,UAAe,GACpB,SAAS,CAuDX;AA4CD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3G,YAAY,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,aAAa,CAAC"}

package/dist/orchestrator.js

@@ -0,0 +1,120 @@
+/**
+ * Public surface of `@albex/ocr`.
+ *
+ * The orchestrator wires an `OcrWorkerPool` to an `AlbexEngine` instance.
+ * After `enableOcr(engine)`:
+ *
+ *   - `engine.ocrImage(blob)` becomes available and returns recognised text.
+ *   - The text can be indexed manually with `engine.indexText(name, text)`
+ *     if such a primitive is exposed by the host (future addition).
+ *
+ * The returned `OcrHandle` lets the caller probe state, query loaded
+ * languages, force pre-load of specific languages, or shut down.
+ */
+import { OcrWorkerPool } from './ocr-worker.js';
+import { SUPPORTED_LANGS } from './language-detector.js';
+import { AlbexOcrError } from './errors.js';
+/**
+ * Hook OCR into an Albex engine. Returns a handle that lets the caller
+ * preload languages, inspect state, and dispose cleanly.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { AlbexEngine } from 'albex';
+ * import { enableOcr } from '@albex/ocr';
+ *
+ * const engine = new AlbexEngine();
+ * await engine.init();
+ *
+ * const ocr = enableOcr(engine, { preload: ['eng', 'spa'] });
+ *
+ * const blob: Blob = await fetch('/scan.png').then(r => r.blob());
+ * const { text } = await engine.ocrImage(blob);
+ * ```
+ */
+export function enableOcr(engine, opts = {}) {
+    if (engine.ocrImage) {
+        throw new AlbexOcrError('ocr_already_enabled', 'enableOcr called on an engine that already has OCR attached. Call dispose() on the previous handle first.');
+    }
+    const enabledLangs = new Set(opts.languages ?? SUPPORTED_LANGS);
+    const defaultLang = opts.defaultLanguage ?? 'eng';
+    const pool = new OcrWorkerPool({
+        idleTimeoutMs: opts.idleTimeoutMs,
+        langPath: opts.langPath,
+    });
+    // Pre-load requested languages without awaiting (fire-and-forget). The
+    // user can also call `handle.preload(...)` to await explicitly.
+    if (opts.preload && opts.preload.length > 0) {
+        void Promise.all(opts.preload
+            .filter(l => enabledLangs.has(l))
+            .map(l => pool.recognize(EMPTY_PIXEL, l).catch(() => { })));
+    }
+    // Attach the recognise method to the engine.
+    engine.ocrImage = async (image, recOpts) => {
+        const targetLang = pickLanguage(recOpts, enabledLangs, defaultLang);
+        return pool.recognize(image, targetLang);
+    };
+    // Hybrid-PDF flag. The engine reads this to decide whether to walk every
+    // PDF's embedded images on top of the normal text extraction. Stored as
+    // a separate slot so the structural contract with `albex` stays minimal.
+    if (opts.alwaysExtractEmbeddedImages) {
+        engine.ocrConfig = { alwaysExtractEmbeddedImages: true };
+    }
+    return {
+        async preload(langs) {
+            await Promise.all(langs
+                .filter(l => enabledLangs.has(l))
+                .map(l => pool.recognize(EMPTY_PIXEL, l).catch(() => { })));
+        },
+        loadedLanguages() {
+            return pool.loadedLanguages();
+        },
+        async dispose() {
+            await pool.dispose();
+            delete engine.ocrImage;
+            delete engine.ocrConfig;
+        },
+    };
+}
+/**
+ * Picks the language for a recognise call. Priority:
+ *   1. Explicit `opts.lang`.
+ *   2. `opts.hint` if enabled.
+ *   3. `defaultLanguage`.
+ *
+ * (Automatic from-text detection happens AFTER the first recognise, not
+ * before — until we have output we have nothing to detect from. A second
+ * pass with the corrected language is a future feature.)
+ */
+function pickLanguage(opts, enabled, fallback) {
+    if (opts?.lang && enabled.has(opts.lang))
+        return opts.lang;
+    if (opts?.hint && enabled.has(opts.hint))
+        return opts.hint;
+    return fallback;
+}
+/**
+ * A 1×1 transparent PNG used to warm a language worker without making real
+ * inference effort. Tesseract.js still bootstraps the LSTM on first
+ * recognise, which is the slow part we want done in advance.
+ */
+const EMPTY_PIXEL = (() => {
+    const bytes = new Uint8Array([
+        0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+        0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
+        0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
+        0x08, 0x06, 0x00, 0x00, 0x00, 0x1F, 0x15, 0xC4,
+        0x89, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x44, 0x41,
+        0x54, 0x78, 0x9C, 0x63, 0x00, 0x01, 0x00, 0x00,
+        0x05, 0x00, 0x01, 0x0D, 0x0A, 0x2D, 0xB4, 0x00,
+        0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE,
+        0x42, 0x60, 0x82,
+    ]);
+    return bytes.buffer;
+})();
+// Re-export the detector so consumers can use it directly when they have
+// known-good source text to identify the document's language before OCR.
+export { detectLanguage, detectLanguageOr, scoreLanguages, SUPPORTED_LANGS } from './language-detector.js';
+export { AlbexOcrError, AlbexOcrInitError, AlbexOcrLanguageError, AlbexOcrRecognitionError, } from './errors.js';
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@albex/ocr",
+  "version": "0.2.0",
+  "description": "OCR module for Albex — Tesseract.js fast, lazy by language, zero-impact on the base bundle.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "albex": "^0.3.0"
+  },
+  "dependencies": {
+    "tesseract.js": "^5.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "ocr",
+    "tesseract",
+    "albex",
+    "wasm",
+    "browser",
+    "search"
+  ],
+  "license": "MIT"
+}

package/src/errors.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 {
+  readonly kind: string;
+  constructor(kind: string, message: string) {
+    super(message);
+    this.name = 'AlbexOcrError';
+    this.kind = kind;
+  }
+}
+
+export class AlbexOcrInitError extends AlbexOcrError {
+  constructor(message: string) {
+    super('ocr_init', message);
+    this.name = 'AlbexOcrInitError';
+  }
+}
+
+export class AlbexOcrLanguageError extends AlbexOcrError {
+  readonly lang: string;
+  constructor(lang: string, message: string) {
+    super('ocr_language', message);
+    this.name = 'AlbexOcrLanguageError';
+    this.lang = lang;
+  }
+}
+
+export class AlbexOcrRecognitionError extends AlbexOcrError {
+  constructor(message: string) {
+    super('ocr_recognition', message);
+    this.name = 'AlbexOcrRecognitionError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * `@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';

package/src/language-detector.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 const SUPPORTED_LANGS: readonly Lang[] = ['eng', 'spa', 'fra', 'deu', 'ita', 'por'];
+
+interface LangProfile {
+  /** Single Unicode characters that strongly suggest this language. */
+  chars: string[];
+  /** Stop words; first ones are most common. */
+  stopWords: string[];
+}
+
+/**
+ * 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: Record<Lang, LangProfile> = {
+  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: string): Record<Lang, number> {
+  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: Record<Lang, number> = { 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: string, minScore = 6): Lang | null {
+  if (text.length < 20) return null; // Nothing to learn from.
+
+  const scores = scoreLanguages(text);
+  let best: Lang | null = 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: string, fallback: Lang = 'eng', minScore = 6): Lang {
+  return detectLanguage(text, minScore) ?? fallback;
+}