@doccloak/core 0.8.0

package/dist/dom/ocr.d.ts

@@ -0,0 +1,112 @@
+/**
+ * OCR support: extract text (with word-level bounding boxes) from images
+ * so it can flow through the regular PII detection pipeline, and render a
+ * redacted copy of the image with detected entities blacked out.
+ *
+ * Uses tesseract.js, which runs Tesseract compiled to WebAssembly inside its
+ * own Web Worker - the image never leaves the browser. Language data is
+ * downloaded once and cached by tesseract.js in IndexedDB.
+ *
+ * Lives under the @doccloak/core/dom submodule: it needs a canvas. Canvas
+ * creation and image decoding are feature-detected so the module also runs in
+ * DOM-less contexts (workers, MV3 offscreen/service contexts) that provide
+ * OffscreenCanvas and createImageBitmap. Tesseract worker/core/lang asset
+ * paths are host-provided via TesseractAssetPaths (core never derives them
+ * from import.meta or its own location).
+ */
+/** Canvas type used throughout OCR: a DOM canvas or an OffscreenCanvas. */
+export type OcrCanvas = HTMLCanvasElement | OffscreenCanvas;
+export interface OcrWord {
+    text: string;
+    /** Character offsets into the reconstructed OCR text */
+    start: number;
+    end: number;
+    /** Pixel bounding box in the OCR'd image's coordinate space */
+    bbox: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+}
+export interface OcrExtraction {
+    text: string;
+    words: OcrWord[];
+}
+/**
+ * Locations of the self-hosted tesseract.js runtime assets, supplied by the
+ * host (web app: `${BASE_URL}tesseract/...` copied by scripts/copy-assets.mjs;
+ * extension: bundled copies). langPath must be an absolute URL - relative
+ * paths are treated as cache keys by the tesseract.js worker, not fetched.
+ */
+export interface TesseractAssetPaths {
+    workerPath: string;
+    corePath: string;
+    langPath: string;
+}
+export declare function isImageFile(fileName: string): boolean;
+/**
+ * Decode an image file into a canvas, downscaling if it exceeds
+ * MAX_IMAGE_DIMENSION. All OCR bounding boxes are relative to the returned
+ * canvas, so redaction is drawn on the same coordinate space.
+ *
+ * Decoding is feature-detected: createImageBitmap where available (all
+ * workers, modern DOM), an HTMLImageElement as the DOM-only fallback.
+ */
+export declare function loadImageToCanvas(file: Blob): Promise<OcrCanvas>;
+/**
+ * Run OCR on a canvas. Returns the extracted text plus per-word character
+ * offsets and pixel bounding boxes. `assets` locates the self-hosted
+ * tesseract.js worker/core/language files (host-provided; see
+ * TesseractAssetPaths). onProgress receives 0..1 during the recognition phase.
+ */
+export declare function recognizeCanvas(canvas: OcrCanvas, uiLanguage: string, assets: TesseractAssetPaths, onProgress?: (progress: number) => void): Promise<OcrExtraction>;
+interface BlockLike {
+    paragraphs: {
+        lines: {
+            words: {
+                text: string;
+                bbox: {
+                    x0: number;
+                    y0: number;
+                    x1: number;
+                    y1: number;
+                };
+            }[];
+        }[];
+    }[];
+}
+/**
+ * Reconstruct plain text from Tesseract's block hierarchy while recording
+ * each word's character range. The reconstruction (not Tesseract's own
+ * `data.text`) is used as the detection input, so entity offsets always map
+ * back to word bounding boxes exactly.
+ *
+ * Exported for tests.
+ */
+export declare function buildTextFromBlocks(blocks: BlockLike[]): OcrExtraction;
+/**
+ * Pick the bounding boxes of every OCR word that overlaps one of the given
+ * character ranges. A word partially covered by a range is fully redacted
+ * (over-redaction is safer than leaking half an identifier).
+ *
+ * Exported for tests.
+ */
+export declare function selectRedactionBoxes(words: OcrWord[], ranges: {
+    start: number;
+    end: number;
+}[]): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}[];
+/**
+ * Draw black boxes over the given character ranges and return the redacted
+ * image as a PNG blob.
+ */
+export declare function renderRedactedImage(sourceCanvas: OcrCanvas, words: OcrWord[], ranges: {
+    start: number;
+    end: number;
+}[]): Promise<Blob>;
+export {};

package/dist/dom/ocr.js

@@ -0,0 +1,224 @@
+/**
+ * OCR support: extract text (with word-level bounding boxes) from images
+ * so it can flow through the regular PII detection pipeline, and render a
+ * redacted copy of the image with detected entities blacked out.
+ *
+ * Uses tesseract.js, which runs Tesseract compiled to WebAssembly inside its
+ * own Web Worker - the image never leaves the browser. Language data is
+ * downloaded once and cached by tesseract.js in IndexedDB.
+ *
+ * Lives under the @doccloak/core/dom submodule: it needs a canvas. Canvas
+ * creation and image decoding are feature-detected so the module also runs in
+ * DOM-less contexts (workers, MV3 offscreen/service contexts) that provide
+ * OffscreenCanvas and createImageBitmap. Tesseract worker/core/lang asset
+ * paths are host-provided via TesseractAssetPaths (core never derives them
+ * from import.meta or its own location).
+ */
+import * as Tesseract from 'tesseract.js';
+/** Images above this dimension are downscaled before OCR to bound memory use on mobile */
+const MAX_IMAGE_DIMENSION = 2560;
+const IMAGE_EXTENSIONS = /\.(png|jpe?g|webp|bmp|gif)$/i;
+/** Map DocCloak UI languages to Tesseract traineddata codes */
+const UI_LANG_TO_TESSERACT = {
+    en: 'eng',
+    pl: 'pol',
+    de: 'deu',
+    fr: 'fra',
+    es: 'spa',
+    pt: 'por',
+    sv: 'swe',
+    no: 'nor',
+};
+export function isImageFile(fileName) {
+    return IMAGE_EXTENSIONS.test(fileName);
+}
+function buildLangList(uiLanguage) {
+    const mapped = UI_LANG_TO_TESSERACT[uiLanguage];
+    if (mapped && mapped !== 'eng')
+        return [mapped, 'eng'];
+    return ['eng'];
+}
+/**
+ * Create a 2D-drawable canvas in whatever context we run in:
+ * a DOM canvas when `document` exists, an OffscreenCanvas otherwise
+ * (workers, MV3 offscreen/service contexts).
+ */
+function createCompatibleCanvas(width, height) {
+    if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        return canvas;
+    }
+    if (typeof OffscreenCanvas !== 'undefined') {
+        return new OffscreenCanvas(width, height);
+    }
+    throw new Error('No canvas implementation available (need document or OffscreenCanvas)');
+}
+function get2dContext(canvas) {
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('Canvas 2D context unavailable');
+    return ctx;
+}
+/**
+ * Decode an image file into a canvas, downscaling if it exceeds
+ * MAX_IMAGE_DIMENSION. All OCR bounding boxes are relative to the returned
+ * canvas, so redaction is drawn on the same coordinate space.
+ *
+ * Decoding is feature-detected: createImageBitmap where available (all
+ * workers, modern DOM), an HTMLImageElement as the DOM-only fallback.
+ */
+export async function loadImageToCanvas(file) {
+    let width;
+    let height;
+    let source;
+    if (typeof createImageBitmap === 'function') {
+        const bitmap = await createImageBitmap(file);
+        width = bitmap.width;
+        height = bitmap.height;
+        source = bitmap;
+    }
+    else {
+        source = await decodeViaImageElement(file);
+        width = source.naturalWidth;
+        height = source.naturalHeight;
+    }
+    const scale = Math.min(1, MAX_IMAGE_DIMENSION / Math.max(width, height));
+    const canvas = createCompatibleCanvas(Math.max(1, Math.round(width * scale)), Math.max(1, Math.round(height * scale)));
+    const ctx = get2dContext(canvas);
+    ctx.drawImage(source, 0, 0, canvas.width, canvas.height);
+    if (typeof source.close === 'function') {
+        source.close();
+    }
+    return canvas;
+}
+function decodeViaImageElement(file) {
+    if (typeof Image === 'undefined') {
+        return Promise.reject(new Error('No image decoder available (need createImageBitmap or Image)'));
+    }
+    return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(file);
+        const img = new Image();
+        img.onload = () => {
+            URL.revokeObjectURL(url);
+            resolve(img);
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(url);
+            reject(new Error('Failed to decode image'));
+        };
+        img.src = url;
+    });
+}
+/**
+ * Run OCR on a canvas. Returns the extracted text plus per-word character
+ * offsets and pixel bounding boxes. `assets` locates the self-hosted
+ * tesseract.js worker/core/language files (host-provided; see
+ * TesseractAssetPaths). onProgress receives 0..1 during the recognition phase.
+ */
+export async function recognizeCanvas(canvas, uiLanguage, assets, onProgress) {
+    onProgress?.(0);
+    const worker = await Tesseract.createWorker(buildLangList(uiLanguage), 1, // OEM.LSTM_ONLY
+    {
+        workerPath: assets.workerPath,
+        corePath: assets.corePath,
+        langPath: assets.langPath,
+        logger: (m) => {
+            if (m.status === 'recognizing text' && typeof m.progress === 'number') {
+                onProgress?.(m.progress);
+            }
+        },
+    });
+    try {
+        const { data } = await worker.recognize(canvas, {}, { blocks: true, text: true });
+        onProgress?.(1);
+        return buildTextFromBlocks(data.blocks ?? []);
+    }
+    finally {
+        await worker.terminate();
+    }
+}
+/**
+ * Reconstruct plain text from Tesseract's block hierarchy while recording
+ * each word's character range. The reconstruction (not Tesseract's own
+ * `data.text`) is used as the detection input, so entity offsets always map
+ * back to word bounding boxes exactly.
+ *
+ * Exported for tests.
+ */
+export function buildTextFromBlocks(blocks) {
+    const words = [];
+    let text = '';
+    for (const block of blocks) {
+        for (const paragraph of block.paragraphs ?? []) {
+            for (const line of paragraph.lines ?? []) {
+                let lineHasWords = false;
+                for (const word of line.words ?? []) {
+                    const value = word.text?.trim();
+                    if (!value)
+                        continue;
+                    if (lineHasWords)
+                        text += ' ';
+                    const start = text.length;
+                    text += value;
+                    words.push({ text: value, start, end: text.length, bbox: word.bbox });
+                    lineHasWords = true;
+                }
+                if (lineHasWords)
+                    text += '\n';
+            }
+        }
+        if (text.length > 0 && !text.endsWith('\n\n'))
+            text += '\n';
+    }
+    return { text: text.trimEnd(), words };
+}
+/**
+ * Pick the bounding boxes of every OCR word that overlaps one of the given
+ * character ranges. A word partially covered by a range is fully redacted
+ * (over-redaction is safer than leaking half an identifier).
+ *
+ * Exported for tests.
+ */
+export function selectRedactionBoxes(words, ranges) {
+    return words
+        .filter((w) => ranges.some((r) => w.start < r.end && w.end > r.start))
+        .map((w) => w.bbox);
+}
+/** Encode a canvas as a PNG blob, whichever canvas flavor it is. */
+function canvasToPngBlob(canvas) {
+    if ('convertToBlob' in canvas) {
+        return canvas.convertToBlob({ type: 'image/png' });
+    }
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (blob)
+                resolve(blob);
+            else
+                reject(new Error('Failed to encode redacted image'));
+        }, 'image/png');
+    });
+}
+/**
+ * Draw black boxes over the given character ranges and return the redacted
+ * image as a PNG blob.
+ */
+export function renderRedactedImage(sourceCanvas, words, ranges) {
+    let canvas;
+    let ctx;
+    try {
+        canvas = createCompatibleCanvas(sourceCanvas.width, sourceCanvas.height);
+        ctx = get2dContext(canvas);
+    }
+    catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+    ctx.drawImage(sourceCanvas, 0, 0);
+    ctx.fillStyle = '#111111';
+    const padding = 2;
+    for (const box of selectRedactionBoxes(words, ranges)) {
+        ctx.fillRect(box.x0 - padding, box.y0 - padding, (box.x1 - box.x0) + padding * 2, (box.y1 - box.y0) + padding * 2);
+    }
+    return canvasToPngBlob(canvas);
+}

package/dist/engine.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @doccloak/core - engine assembly (T009).
+ *
+ * createEngine() turns the injected CoreEnv plus the two built-in detection
+ * providers into a DocCloakEngine: provider registry, settings persisted
+ * through env.kv under the exact localStorage keys the web app has always
+ * used (see ENGINE_SETTINGS_KEYS - no prefixing, so pre-extraction user
+ * profiles read back unchanged), per-provider threshold defaults, progress
+ * event fan-out and the mobile/low-memory default-model heuristic fed by
+ * env.hardware.
+ *
+ * The engine is transport-agnostic; worker-protocol.ts serves it over any
+ * PortLike transport (Web Worker postMessage, MessageChannel, extension
+ * ports).
+ */
+import type { CoreEnv, HardwareHints } from './env.js';
+import type { DetectedEntity, DetectionProvider } from './types.js';
+import { type RegexRegionId } from './regex/index.js';
+export type ProviderId = 'gliner' | 'bardsai';
+export interface ProviderEntry {
+    id: ProviderId;
+    label: string;
+    description: string;
+}
+/** Catalog of the built-in providers (labels/descriptions shown by hosts). */
+export declare const PROVIDERS: ProviderEntry[];
+export type ProviderFactory = (env: CoreEnv) => DetectionProvider;
+export interface EngineOptions {
+    /** Override provider construction (tests inject deterministic stubs). */
+    providers?: Partial<Record<ProviderId, ProviderFactory>>;
+}
+/**
+ * env.kv keys, byte-identical to the localStorage keys the web app used
+ * before the extraction. A 1:1 KV adapter (no prefixing) therefore reads a
+ * legacy profile back correctly.
+ */
+export declare const ENGINE_SETTINGS_KEYS: {
+    readonly provider: "doccloak-active-provider";
+    readonly customLabels: "doccloak-custom-labels";
+    readonly regexEnabled: "doccloak-regex-enabled";
+    readonly regexRegion: "doccloak-regex-region";
+};
+export interface EngineSettings {
+    providerId: ProviderId;
+    /** Not persisted (matches the pre-extraction behavior): resets to the provider default on init/switch. */
+    threshold: number;
+    regexEnabled: boolean;
+    regexRegion: RegexRegionId;
+    customLabels: string[];
+}
+export interface DocCloakEngine {
+    /** Resolves once persisted settings have been read from env.kv. */
+    readonly ready: Promise<void>;
+    detect(text: string, signal?: AbortSignal, onProgress?: (progress: number) => void): Promise<DetectedEntity[]>;
+    /** Download + init the current provider. */
+    preload(): Promise<void>;
+    switchProvider(id: ProviderId): Promise<void>;
+    getSettings(): EngineSettings;
+    /** Merges the patch, persists via env.kv and applies it to the live provider. */
+    updateSettings(patch: Partial<EngineSettings>): Promise<void>;
+    onDownloadProgress(cb: (p: {
+        loaded: number;
+        total: number;
+    }) => void): () => void;
+    onDetectionProgress(cb: (progress: number) => void): () => void;
+    /** Free ONNX session memory; the model reloads on the next detect/preload. */
+    release(): Promise<void>;
+}
+/** Per-provider confidence threshold defaults. */
+export declare function defaultThresholdFor(id: ProviderId): number;
+/** Clamp a detection threshold to the supported 0.05-0.95 range. */
+export declare function clampThreshold(value: number): number;
+/**
+ * Default-model heuristic for devices without a saved provider choice.
+ * The BardS.ai model (~279 MB download, ~500+ MB peak RAM while loading)
+ * routinely gets the tab killed on mobile browsers, so constrained devices
+ * default to the lightweight GLiNER model (~65 MB). Hosts feed the hints
+ * (userAgent/deviceMemory sniffing stays host-side).
+ */
+export declare function pickDefaultProvider(hardware?: HardwareHints): ProviderId;
+export declare function createEngine(env: CoreEnv, initial?: Partial<EngineSettings>, options?: EngineOptions): DocCloakEngine;

package/dist/engine.js

@@ -0,0 +1,274 @@
+/**
+ * @doccloak/core - engine assembly (T009).
+ *
+ * createEngine() turns the injected CoreEnv plus the two built-in detection
+ * providers into a DocCloakEngine: provider registry, settings persisted
+ * through env.kv under the exact localStorage keys the web app has always
+ * used (see ENGINE_SETTINGS_KEYS - no prefixing, so pre-extraction user
+ * profiles read back unchanged), per-provider threshold defaults, progress
+ * event fan-out and the mobile/low-memory default-model heuristic fed by
+ * env.hardware.
+ *
+ * The engine is transport-agnostic; worker-protocol.ts serves it over any
+ * PortLike transport (Web Worker postMessage, MessageChannel, extension
+ * ports).
+ */
+import { detectWithRegex, detectEntities } from "./pipeline.js";
+import { GlinerProvider } from "./providers/gliner.js";
+import { BardsaiProvider } from "./providers/bardsai.js";
+import { REGEX_REGIONS } from "./regex/index.js";
+/** Catalog of the built-in providers (labels/descriptions shown by hosts). */
+export const PROVIDERS = [
+    {
+        id: 'gliner',
+        label: 'GLiNER PII Edge',
+        description: 'Lightweight, multi-language, supports custom labels (~65 MB)',
+    },
+    {
+        id: 'bardsai',
+        label: 'BardS.ai EU PII',
+        description: '24 EU languages, 35 PII types, high accuracy (~279 MB)',
+    },
+];
+// ── Settings ───────────────────────────────────────────────
+/**
+ * env.kv keys, byte-identical to the localStorage keys the web app used
+ * before the extraction. A 1:1 KV adapter (no prefixing) therefore reads a
+ * legacy profile back correctly.
+ */
+export const ENGINE_SETTINGS_KEYS = {
+    provider: 'doccloak-active-provider',
+    customLabels: 'doccloak-custom-labels',
+    regexEnabled: 'doccloak-regex-enabled',
+    regexRegion: 'doccloak-regex-region',
+};
+// ── Helpers ────────────────────────────────────────────────
+/** Per-provider confidence threshold defaults. */
+export function defaultThresholdFor(id) {
+    return id === 'bardsai' ? 0.5 : 0.35;
+}
+/** Clamp a detection threshold to the supported 0.05-0.95 range. */
+export function clampThreshold(value) {
+    return Math.max(0.05, Math.min(0.95, value));
+}
+/**
+ * Default-model heuristic for devices without a saved provider choice.
+ * The BardS.ai model (~279 MB download, ~500+ MB peak RAM while loading)
+ * routinely gets the tab killed on mobile browsers, so constrained devices
+ * default to the lightweight GLiNER model (~65 MB). Hosts feed the hints
+ * (userAgent/deviceMemory sniffing stays host-side).
+ */
+export function pickDefaultProvider(hardware) {
+    if (hardware?.isMobile)
+        return 'gliner';
+    if (typeof hardware?.deviceMemoryGB === 'number' && hardware.deviceMemoryGB <= 4)
+        return 'gliner';
+    return 'bardsai';
+}
+function isProviderId(value) {
+    return PROVIDERS.some((p) => p.id === value);
+}
+function isRegexRegionId(value) {
+    return typeof value === 'string' && REGEX_REGIONS.includes(value);
+}
+function supportsCustomLabels(p) {
+    return 'setCustomLabels' in p;
+}
+// ── Engine ─────────────────────────────────────────────────
+export function createEngine(env, initial, options) {
+    const factories = {
+        gliner: (e) => new GlinerProvider(e),
+        bardsai: (e) => new BardsaiProvider(e),
+        ...options?.providers,
+    };
+    const settings = {
+        providerId: initial?.providerId ?? pickDefaultProvider(env.hardware),
+        threshold: 0,
+        regexEnabled: initial?.regexEnabled ?? false,
+        regexRegion: initial?.regexRegion ?? 'all',
+        customLabels: [...(initial?.customLabels ?? [])],
+    };
+    settings.threshold = initial?.threshold !== undefined
+        ? clampThreshold(initial.threshold)
+        : defaultThresholdFor(settings.providerId);
+    /** Load persisted settings; explicit `initial` values win over env.kv. */
+    const ready = (async () => {
+        if (initial?.providerId === undefined) {
+            try {
+                const saved = await env.kv.get(ENGINE_SETTINGS_KEYS.provider);
+                if (isProviderId(saved)) {
+                    settings.providerId = saved;
+                    if (initial?.threshold === undefined)
+                        settings.threshold = defaultThresholdFor(saved);
+                }
+            }
+            catch { /* KV unavailable - keep the heuristic default */ }
+        }
+        if (initial?.customLabels === undefined) {
+            try {
+                const saved = await env.kv.get(ENGINE_SETTINGS_KEYS.customLabels);
+                if (saved) {
+                    const parsed = JSON.parse(saved);
+                    if (Array.isArray(parsed)) {
+                        settings.customLabels = parsed.filter((l) => typeof l === 'string');
+                    }
+                }
+            }
+            catch { /* unreadable value - keep default */ }
+        }
+        if (initial?.regexEnabled === undefined) {
+            try {
+                const saved = await env.kv.get(ENGINE_SETTINGS_KEYS.regexEnabled);
+                if (saved !== null)
+                    settings.regexEnabled = JSON.parse(saved) === true;
+            }
+            catch { /* unreadable value - keep default */ }
+        }
+        if (initial?.regexRegion === undefined) {
+            try {
+                const saved = await env.kv.get(ENGINE_SETTINGS_KEYS.regexRegion);
+                if (isRegexRegionId(saved))
+                    settings.regexRegion = saved;
+            }
+            catch { /* unreadable value - keep default */ }
+        }
+    })();
+    let provider = null;
+    let inflightLoad = null;
+    const downloadListeners = new Set();
+    const detectionListeners = new Set();
+    async function kvSet(key, value) {
+        try {
+            await env.kv.set(key, value);
+        }
+        catch { /* KV unavailable (e.g. storage-less worker) - settings stay in memory */ }
+    }
+    function ensureProvider() {
+        if (!provider) {
+            const factory = factories[settings.providerId];
+            if (!factory)
+                throw new Error(`Unknown provider: ${settings.providerId}`);
+            provider = factory(env);
+            provider.onProgress((downloaded, total) => {
+                for (const cb of downloadListeners)
+                    cb({ loaded: downloaded, total });
+            });
+        }
+        return provider;
+    }
+    async function applyCustomLabels(p) {
+        if (supportsCustomLabels(p)) {
+            await p.setCustomLabels(settings.customLabels);
+        }
+    }
+    async function preload() {
+        await ready;
+        if (inflightLoad)
+            return inflightLoad;
+        const p = ensureProvider();
+        if (p.isLoaded())
+            return;
+        inflightLoad = (async () => {
+            // A previous attempt may have failed: release() clears the cached load
+            // error so load() can retry (model bytes are served from the blob
+            // cache when available). Mirrors the old worker init path.
+            if (!p.isLoading())
+                p.release();
+            await applyCustomLabels(p);
+            await p.load();
+            settings.threshold = p.getThreshold();
+            if (supportsCustomLabels(p))
+                settings.customLabels = p.getCustomLabels();
+        })();
+        try {
+            await inflightLoad;
+        }
+        finally {
+            inflightLoad = null;
+        }
+    }
+    async function switchProvider(id) {
+        await ready;
+        if (!factories[id])
+            throw new Error(`Unknown provider: ${id}`);
+        if (id === settings.providerId && provider?.isLoaded())
+            return;
+        // Release the previous ONNX session to free WASM heap. Cached model
+        // files are kept so switching back does not re-download hundreds of
+        // megabytes; the browser evicts them under quota pressure.
+        provider?.release();
+        provider = null;
+        settings.providerId = id;
+        settings.threshold = defaultThresholdFor(id);
+        await kvSet(ENGINE_SETTINGS_KEYS.provider, id);
+        await preload();
+    }
+    async function updateSettings(patch) {
+        await ready;
+        if (patch.providerId !== undefined && patch.providerId !== settings.providerId) {
+            if (!factories[patch.providerId])
+                throw new Error(`Unknown provider: ${patch.providerId}`);
+            provider?.release();
+            provider = null;
+            settings.providerId = patch.providerId;
+            settings.threshold = defaultThresholdFor(patch.providerId);
+            await kvSet(ENGINE_SETTINGS_KEYS.provider, patch.providerId);
+        }
+        if (patch.threshold !== undefined) {
+            settings.threshold = clampThreshold(patch.threshold);
+            provider?.setThreshold(settings.threshold);
+        }
+        if (patch.customLabels !== undefined) {
+            settings.customLabels = patch.customLabels.filter((l) => l.trim().length > 0);
+            await kvSet(ENGINE_SETTINGS_KEYS.customLabels, JSON.stringify(settings.customLabels));
+            if (provider)
+                await applyCustomLabels(provider);
+        }
+        if (patch.regexEnabled !== undefined) {
+            settings.regexEnabled = patch.regexEnabled;
+            await kvSet(ENGINE_SETTINGS_KEYS.regexEnabled, JSON.stringify(patch.regexEnabled));
+        }
+        if (patch.regexRegion !== undefined) {
+            settings.regexRegion = patch.regexRegion;
+            await kvSet(ENGINE_SETTINGS_KEYS.regexRegion, patch.regexRegion);
+        }
+    }
+    async function detect(text, signal, onProgress) {
+        await ready;
+        if (signal?.aborted)
+            throw new Error('Detection aborted');
+        if (!text.trim())
+            return [];
+        const p = ensureProvider();
+        const mlResults = await p.detect(text, (progress) => {
+            onProgress?.(progress);
+            for (const cb of detectionListeners)
+                cb(progress);
+        });
+        if (signal?.aborted)
+            throw new Error('Detection aborted');
+        const regexResults = settings.regexEnabled ? detectWithRegex(text, settings.regexRegion) : [];
+        return detectEntities(text, mlResults, regexResults);
+    }
+    return {
+        ready,
+        detect,
+        preload,
+        switchProvider,
+        getSettings() {
+            return { ...settings, customLabels: [...settings.customLabels] };
+        },
+        updateSettings,
+        onDownloadProgress(cb) {
+            downloadListeners.add(cb);
+            return () => downloadListeners.delete(cb);
+        },
+        onDetectionProgress(cb) {
+            detectionListeners.add(cb);
+            return () => detectionListeners.delete(cb);
+        },
+        async release() {
+            provider?.release();
+        },
+    };
+}