albex 0.1.0 → 0.6.0

package/dist/albex.js

@@ -1,3 +1,10 @@
+/*!
+ * albex v0.6.0
+ * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
+ * (c) 2026 RafaCalRob
+ * @license MIT
+ * https://github.com/RafaCalRob/Albex#readme
+ */
 /**
  * Albex — local full-text search engine.
  *
@@ -13,41 +20,64 @@
  * const results = engine.search('contrato marco');
  * ```
  */
-function tokenize(q) {
-    return q.trim().split(/\s+/).filter(t => t.length > 0);
-}
-function parseQuery(q) {
-    const trimmed = q.trim();
-    // OR: "term1 | term2" or "phrase one | phrase two"
-    if (trimmed.includes('|')) {
-        const branches = trimmed.split('|')
-            .map(p => tokenize(p.replace(/"/g, '')))
-            .filter(b => b.length > 0);
-        return { kind: 'or', branches };
-    }
-    // Phrase: "exact phrase here"
-    const phraseMatch = /^"(.+)"$/.exec(trimmed);
-    if (phraseMatch) {
-        const inner = phraseMatch[1] ?? '';
-        const tokens = tokenize(inner);
-        return { kind: 'phrase', tokens, raw: inner };
-    }
-    return { kind: 'simple', tokens: tokenize(trimmed) };
-}
-/**
- * Reconstruct a WASM-compatible query string from parsed tokens.
- * The WASM engine accepts up to 4 space-separated tokens (AND semantics).
- */
-function tokensToWasmQuery(tokens) {
-    return tokens.slice(0, 4).join(' ');
+import { asAlbexExports, asAlbexPdfExports, } from './wasm-bindings.js';
+import { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
+import { savePersisted, loadPersisted, deletePersisted, listPersisted, } from './persistence.js';
+import { detectProfile, shouldUseGpu } from './profile.js';
+import { getResourceManager } from './resource-manager.js';
+import { BloomGpu, packBloomsFromChunks } from './gpu/bloom-runtime.js';
+export { AlbexError, AlbexInitError, AlbexUnsupportedFormatError, AlbexParseError, AlbexCapacityError, } from './errors.js';
+export { listPersisted, deletePersisted } from './persistence.js';
+export { detectProfile, pickTier, pickWorkerCount, shouldUseGpu } from './profile.js';
+export { getResourceManager } from './resource-manager.js';
+export { AlbexPool } from './pool/coordinator.js';
+export { BloomGpu, packBloomsFromChunks } from './gpu/bloom-runtime.js';
+export { TieredStore } from './tiered-store.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Deprecation warnings — one-shot, fire-and-forget
+// ─────────────────────────────────────────────────────────────────────────────
+let _searchStreamWarned = false;
+function warnSearchStreamDeprecated() {
+    if (_searchStreamWarned)
+        return;
+    _searchStreamWarned = true;
+    // The original name implied incremental streaming, which the implementation
+    // never provided. Renamed in 0.3.0; alias removed in 0.4.0.
+    console.warn('[albex] `searchStream` is deprecated; rename to `searchCooperative`. ' +
+        'The method does not stream incremental results — it yields to the ' +
+        'scheduler between slices and returns a batch. The alias will be ' +
+        'removed in 0.4.0.');
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// Phrase post-filter
+// Query parsing (WASM-side as of 0.5.0)
 // ─────────────────────────────────────────────────────────────────────────────
+//
+// Pre-0.5.0 this file owned parseQuery + tokenize. That created two
+// truths about what a "token" was: one in TS for the query, one in Rust
+// for the indexed text. The audit flagged this as the biggest divergence
+// in the wrapper.
+//
+// 0.5.0 moves parseQuery/tokenize/tokensToWasmQuery to Rust. The TS
+// dispatcher reduces to:
+//
+//   1. Write the raw UTF-8 query bytes to the scratchpad.
+//   2. Call prepareQuery(len). Get back the kind (simple/phrase/or).
+//   3. For OR: iterate getQueryBranchCount() branches, calling
+//      selectQueryBranch(i) + search() for each, then merge in TS.
+//      For simple/phrase: selectQueryBranch(0) + search().
+//   4. For phrase: post-filter the snippets with containsPhrase().
+//
+// containsPhrase stays in TS because it operates on snippet text already
+// produced by the WASM, not on the query. It is not a tokenizer.
 /**
- * Returns true if `snippet` contains the phrase formed by `tokens` in order,
- * with at most `maxGap` characters between consecutive tokens.
- * Comparison is case- and accent-insensitive.
+ * Phrase post-filter. Returns true if `snippet` contains the phrase
+ * formed by `tokens` in order, with at most `maxGap` characters between
+ * consecutive tokens. Comparison is case- and accent-insensitive.
+ *
+ * The tokens come from the WASM-compiled pattern of a phrase branch,
+ * not from a TS re-tokenization of the query, so there is no
+ * tokenization divergence: WASM said "these are the tokens", we just
+ * check adjacency in the snippet.
  */
 function containsPhrase(snippet, tokens, maxGap = 30) {
     const norm = (s) => s.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
@@ -80,7 +110,7 @@ function zipCentralDir(bytes) {
     while (p >= 0 && v.getUint32(p, true) !== 0x06054b50)
         p--;
     if (p < 0)
-        throw new Error('Not a ZIP file');
+        throw new AlbexParseError('zip', 'Not a ZIP file (no EOCD record)');
     return { v, cdOff: v.getUint32(p + 16, true), cdN: v.getUint16(p + 10, true) };
 }
 function listZipEntries(bytes) {
@@ -109,7 +139,7 @@ async function findZipEntry(bytes, name) {
         }
         cp += 46 + nl + xl + cl;
     }
-    throw new Error(`Entry "${name}" not found in ZIP`);
+    throw new AlbexParseError('zip', `Entry "${name}" not found in ZIP`);
 }
 async function decompEntry(bytes, v, off, compSize) {
     const meth = v.getUint16(off + 8, true);
@@ -146,62 +176,508 @@ async function decompEntry(bytes, v, off, compSize) {
         }
         return out;
     }
-    throw new Error(`Unsupported ZIP compression method ${meth}`);
+    throw new AlbexParseError('zip', `Unsupported ZIP compression method ${meth}`);
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // WASM memory helpers (internal)
 // ─────────────────────────────────────────────────────────────────────────────
-const FEED_SIZE = 32768; // 32 KB — fits in 64 KB scratchpad
+const FEED_SIZE = 32_768; // 32 KB — fits in 64 KB scratchpad
+// ─────────────────────────────────────────────────────────────────────────────
+// Content hash — FNV-1a 64-bit
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Compute a 64-bit FNV-1a hash of `bytes` and return it as a 16-char hex
+ * string. FNV-1a is a non-cryptographic hash; chosen here because:
+ *   - it needs zero dependencies,
+ *   - it is fast on small/medium blobs (~100 MB/s in modern JS),
+ *   - 64 bits is enough to deduplicate documents in a 128-doc library with
+ *     vanishing collision probability.
+ *
+ * The result is stable across runs and engines, so it can be persisted in
+ * snapshots without versioning concerns.
+ */
+/**
+ * Compute the same 64-bit Bloom value the Rust side computes for a query.
+ *
+ * Must stay in sync with `BloomFilter::from_text` and `fold_utf8_char` in
+ * `core/src/bloom.rs`. The hashing is `c & 0x3F` over each accent-folded
+ * lowercase ASCII byte; non-letters are skipped. The aggregate of all token
+ * blooms is what the GPU pre-filter checks against.
+ */
+function computePatternBloom(query) {
+    // Quick-and-faithful fold: lowercase, NFKD, strip combining marks. This
+    // matches the Rust Latin-1/Latin-A fold for the characters we care about
+    // (the rest fall through as non-letters which contribute nothing).
+    const norm = query.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
+    let bits = 0n;
+    for (let i = 0; i < norm.length; i++) {
+        const code = norm.charCodeAt(i);
+        if ((code >= 0x61 && code <= 0x7a) || (code >= 0x30 && code <= 0x39)) {
+            bits |= 1n << BigInt(code & 0x3f);
+        }
+        else if (code === 0x20) {
+            // skip token separator
+        }
+        else if (code < 0x80) {
+            // other ASCII punctuation — they bias the filter; mirror Rust which
+            // also includes them via the 6-bit mask.
+            bits |= 1n << BigInt(code & 0x3f);
+        }
+    }
+    return bits;
+}
+// Note: `contentHash` is implemented as a method on AlbexEngine below
+// (it needs access to the WASM scratchpad). The standalone TS reference
+// implementation that used to live here was removed in 0.4.0 — the
+// canonical hash now lives in wasm/src/lib.rs::hashBytes so there is
+// exactly one definition of "the content hash of these bytes".
+/**
+ * 16-hex-char content hash → 8 raw bytes for setDocumentContentHash. The
+ * byte order matches the snapshot format: the high 32 bits sit at offsets
+ * 0..3 (big-endian-of-the-half), the low 32 bits at offsets 4..7. The
+ * exact byte order is irrelevant for correctness — both encode and decode
+ * use the same convention — but matching the natural hex byte order keeps
+ * a hex dump readable.
+ */
+function hashHexToBytes(hex) {
+    const out = new Uint8Array(8);
+    for (let i = 0; i < 8; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * Map a Windows-1252 byte to its Unicode equivalent. Used by the RTF parser
+ * for `\'XX` escapes — RTF defaults to cp1252 for high-ANSI characters.
+ *
+ * The 0x80-0x9F range is what makes cp1252 ≠ Latin-1: Microsoft put curly
+ * quotes, em-dashes, the Euro sign etc. into this otherwise-control-only
+ * block. Outside that range, cp1252 matches Latin-1 (which equals Unicode
+ * for codepoints below 0x100).
+ */
+const _CP1252_HIGH = {
+    0x80: '€', 0x82: '‚', 0x83: 'ƒ', 0x84: '„', 0x85: '…', 0x86: '†',
+    0x87: '‡', 0x88: 'ˆ', 0x89: '‰', 0x8A: 'Š', 0x8B: '‹', 0x8C: 'Œ',
+    0x8E: 'Ž',
+    0x91: '‘', 0x92: '’', 0x93: '“', 0x94: '”',
+    0x95: '•', 0x96: '–', 0x97: '—', 0x98: '˜', 0x99: '™', 0x9A: 'š',
+    0x9B: '›', 0x9C: 'œ', 0x9E: 'ž', 0x9F: 'Ÿ',
+};
+function rtfCp1252ToChar(byte) {
+    if (byte < 0x80)
+        return String.fromCharCode(byte);
+    if (byte >= 0xA0)
+        return String.fromCharCode(byte);
+    return _CP1252_HIGH[byte] ?? '';
+}
+/**
+ * Apply the entity's Content-Transfer-Encoding to its body. Handles
+ * base64, quoted-printable, and the pass-through cases (7bit, 8bit, none).
+ * Anything unrecognised falls through as pass-through too — better to
+ * index something marginally useful than to drop the body entirely.
+ */
+function decodeEmlBody(headersBlock, body, header) {
+    const enc = header(headersBlock, 'Content-Transfer-Encoding').toLowerCase();
+    if (enc === 'base64')
+        return decodeBase64Utf8(body);
+    if (enc === 'quoted-printable')
+        return decodeQuotedPrintable(body);
+    return body;
+}
+/**
+ * Decode a base64 body and interpret the result as UTF-8 text. Used by the
+ * EML parser when Content-Transfer-Encoding is base64. Whitespace inside
+ * the encoded body (the line breaks every 76 chars) is stripped first;
+ * malformed inputs fall back to returning the original string so the
+ * caller can still index *something*.
+ */
+function decodeBase64Utf8(body) {
+    try {
+        const clean = body.replace(/\s+/g, '');
+        if (!clean)
+            return '';
+        // atob produces a "binary string" where each char's low byte is the
+        // original byte. We have to bridge that back through Uint8Array to
+        // decode UTF-8 multi-byte sequences correctly.
+        const bin = atob(clean);
+        const arr = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            arr[i] = bin.charCodeAt(i);
+        return _dec.decode(arr);
+    }
+    catch {
+        return body;
+    }
+}
+/**
+ * Decode a quoted-printable body. Handles `=XX` hex escapes (including the
+ * `=` "soft line break" producing nothing) and re-decodes the result as
+ * UTF-8 — RFC 2045 allows non-ASCII bytes to be QP-encoded, so multiple
+ * hex pairs in a row may form a single UTF-8 codepoint.
+ */
+function decodeQuotedPrintable(body) {
+    // First pass: collect the raw bytes so we can decode multi-byte UTF-8.
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '=') {
+            // Soft line break: `=` at end of line.
+            if (body[i + 1] === '\n') {
+                i += 1;
+                continue;
+            }
+            // `=XX` hex pair.
+            const h = body.slice(i + 1, i + 3);
+            if (/^[0-9A-Fa-f]{2}$/.test(h)) {
+                bytes.push(parseInt(h, 16));
+                i += 2;
+                continue;
+            }
+            // Malformed: keep the literal `=`.
+            bytes.push(0x3D);
+            continue;
+        }
+        // ASCII pass-through. JS strings are UTF-16; for ASCII we know
+        // charCodeAt fits in a byte. Non-ASCII char in the source isn't
+        // strictly valid QP but we pass it through best-effort.
+        bytes.push(c.charCodeAt(0) & 0xff);
+    }
+    try {
+        return _dec.decode(new Uint8Array(bytes));
+    }
+    catch {
+        return body;
+    }
+}
+/** Inverse of hashHexToBytes. All-zero bytes return '' (no hash known). */
+function hashBytesToHex(bytes) {
+    let allZero = true;
+    for (let i = 0; i < 8; i++) {
+        if (bytes[i] !== 0) {
+            allZero = false;
+            break;
+        }
+    }
+    if (allZero)
+        return '';
+    let s = '';
+    for (let i = 0; i < 8; i++) {
+        s += bytes[i].toString(16).padStart(2, '0');
+    }
+    return s;
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // PDF WASM imports shim
 // ─────────────────────────────────────────────────────────────────────────────
-function makePdfWasmImports(getPdfMem) {
+/**
+ * Build the import object for `albex_pdf.wasm` by inspecting the module's
+ * required imports at instantiation time.
+ *
+ * The PDF wasm pulls `wasm-bindgen` transitively through `getrandom`. Its
+ * import names embed a build-time hash, e.g.
+ *   __wbg_getRandomValues_3f44b700395062e5
+ * Hardcoding that hash bound the loader to one exact build of the .wasm —
+ * any version bump of getrandom / lopdf / wasm-bindgen silently broke
+ * instantiation with an InputValidationError.
+ *
+ * Here we resolve imports by *prefix* and module so the binding survives
+ * cosmetic mangling changes. We map:
+ *   - any  __wbg_getRandomValues_* / __wbg_crypto_*    → crypto.getRandomValues
+ *   - any  __wbindgen_describe* / __wbindgen_throw*    → no-op
+ *   - __wbindgen_object_drop_ref                       → heap-slot recycler
+ *   - __wbindgen_externref_table_grow                  → heap grower
+ *   - __wbindgen_externref_table_set_null              → heap nuller
+ *
+ * Anything else gets a logged no-op stub. If the PDF code path ever exercises
+ * a missing import, the user gets a console warning, not a hard crash on load.
+ */
+function makePdfWasmImports(module, getPdfMem) {
     const heap = [];
     let freeIdx = -1;
-    return {
-        __wbindgen_placeholder__: {
-            __wbindgen_describe: () => { },
-            __wbg_getRandomValues_3f44b700395062e5: (ptr, len) => {
-                const mem = getPdfMem();
-                crypto.getRandomValues(new Uint8Array(mem.buffer, ptr >>> 0, len >>> 0));
-            },
-            __wbindgen_object_drop_ref: (idx) => {
-                heap[idx] = freeIdx;
-                freeIdx = idx;
-            },
-        },
-        __wbindgen_externref_xform__: {
-            __wbindgen_externref_table_grow: (delta) => {
-                const old = heap.length;
-                for (let i = 0; i < delta; i++)
-                    heap.push(undefined);
-                return old;
-            },
-            __wbindgen_externref_table_set_null: (idx) => { heap[idx] = undefined; },
-        },
+    const required = WebAssembly.Module.imports(module);
+    const fillRandom = (ptr, len) => {
+        const mem = getPdfMem();
+        if (!mem)
+            throw new Error('PDF WASM memory not initialised');
+        crypto.getRandomValues(new Uint8Array(mem.buffer, ptr >>> 0, len >>> 0));
     };
+    const resolveByName = (modName, name) => {
+        // Random-byte providers (any hashed variant).
+        if (name.startsWith('__wbg_getRandomValues') || name.startsWith('__wbg_crypto')) {
+            return fillRandom;
+        }
+        // Diagnostic / introspection — never invoked at runtime in our paths.
+        if (name.startsWith('__wbindgen_describe') || name.startsWith('__wbindgen_throw')) {
+            return () => { };
+        }
+        // Externref-heap management used by wasm-bindgen runtime.
+        switch (name) {
+            case '__wbindgen_object_drop_ref':
+                return (idx) => { heap[idx] = freeIdx; freeIdx = idx; };
+            case '__wbindgen_externref_table_grow':
+                return (delta) => {
+                    const old = heap.length;
+                    for (let i = 0; i < delta; i++)
+                        heap.push(undefined);
+                    return old;
+                };
+            case '__wbindgen_externref_table_set_null':
+                return (idx) => { heap[idx] = undefined; };
+        }
+        // Unknown import — fail fast. An import we don't recognise means the
+        // wasm-bindgen / lopdf / getrandom dependency graph has drifted from
+        // the prefixes this loader is written to satisfy. Accepting the
+        // module would defer the failure to an arbitrary execution path,
+        // typically deep inside extractPdf(), where the user gets either a
+        // hang or a misleading "PDF parse error". Refusing instantiation
+        // surfaces the version skew at boot, where the maintainer can act
+        // on it.
+        throw new AlbexInitError(`Unknown PDF WASM import "${modName}.${name}". ` +
+            `The albex_pdf.wasm binary was probably built with a newer Rust ` +
+            `toolchain or dependency graph than this loader was written for. ` +
+            `Rebuild with 'npm run build:pdf-wasm' or open an issue.`);
+    };
+    const imports = {};
+    for (const { module: modName, name } of required) {
+        if (!imports[modName])
+            imports[modName] = {};
+        imports[modName][name] = resolveByName(modName, name);
+    }
+    return imports;
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// AlbexEngine
-// ─────────────────────────────────────────────────────────────────────────────
 export class AlbexEngine {
+    // ── main WASM ──
+    _wasm;
+    _mem;
+    /**
+     * OCR entry point installed by `@albex/ocr::enableOcr(engine)`. Undefined
+     * when the OCR module has not been wired. The main `albex` package has no
+     * runtime dependency on OCR — this is a structural slot that the optional
+     * companion package fills.
+     */
+    /**
+     * Public OCR entry point. Forwards to the attached OCR adapter installed
+     * via `attachOcr()`. Reading this property is a feature-detect for
+     * integrators: `if (engine.ocrImage) { ... OCR available ... }`. Writing
+     * to it directly is no longer supported in 0.5.0+ — use `attachOcr`.
+     */
+    get ocrImage() {
+        return this._ocrAdapter?.recognize;
+    }
+    /** Private adapter slot. Holds the OCR plugin contract installed by
+     * `attachOcr()`. The engine reads `recognize` and `options` here; the
+     * caller never gets a reference to this object directly. */
+    _ocrAdapter = null;
+    // ── PDF WASM (lazy) ──
+    _pdfWasm = null;
+    _pdfMem = null;
+    _docs = [];
+    _lastSearch = null;
+    /** Structured diagnostics collected during the most recent operation.
+     * Drained by `takeDiagnostics()`. Capped at 256 entries to avoid
+     * unbounded memory growth in pathological cases (very corrupted
+     * corpora producing thousands of recovery warnings). */
+    _diagnostics = [];
+    _tier = null;
+    _simd = false;
+    _profile = null;
+    _resources = null;
+    _gpu = null;
+    _gpuChunkCountUploaded = 0;
+    _unsubscribeResources = null;
+    _opts;
+    // ── Concurrency guard ──────────────────────────────────────────────────────
+    // One WASM instance, global mutable state, async ops that yield to the
+    // scheduler between slices. Two overlapping operations corrupt each other
+    // (e.g. a fresh searchBegin resets the cursor of an in-flight cooperative
+    // search). Async ops serialize through `_opChain`; sync mutators/searches
+    // assert the engine is idle (audit 0.6.0, finding #2).
+    _opChain = Promise.resolve();
+    _busy = false;
     constructor(opts) {
-        // ── PDF WASM (lazy) ──
-        this._pdfWasm = null;
-        this._pdfMem = null;
-        this._docs = [];
-        this._lastSearch = null;
         this._opts = opts;
     }
+    /** Serialize an async engine operation behind any in-flight one. */
+    _exclusive(fn) {
+        const run = this._opChain.then(async () => {
+            this._busy = true;
+            try {
+                return await fn();
+            }
+            finally {
+                this._busy = false;
+            }
+        });
+        // Swallow result/error on the chain so one failure can't wedge the queue.
+        this._opChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Guard a synchronous mutator/search: refuse to run mid-async-operation
+     * rather than silently corrupt the shared WASM state. */
+    _assertIdle(method) {
+        if (this._busy) {
+            throw new AlbexError('busy', `${method}() was called while an async engine operation is still ` +
+                `running. Await the previous indexFile/save/load/replaceDocument/` +
+                `searchCooperative call, or use searchCooperative instead of search().`);
+        }
+    }
+    /** Compact opportunistically when tombstones pile up under text pressure,
+     * so repeated removeDocument/replaceDocument don't exhaust the pool. */
+    _autoCompactIfNeeded() {
+        const w = this._wasm;
+        const cap = w.getTextCapacity();
+        const hasTombstones = w.getDocCount() > this._docs.length;
+        if (hasTombstones && cap > 0 && w.getTextUsed() / cap > 0.85) {
+            w.compact();
+        }
+    }
     /** Load and initialise the main WASM module. Must be called before any other method. */
     async init() {
-        const res = await fetch(this._opts.wasmUrl);
+        const url = await this._resolveWasmUrl();
+        const res = await fetch(url);
         if (!res.ok)
-            throw new Error(`Failed to fetch WASM: ${res.status}`);
+            throw new AlbexInitError(`Failed to fetch WASM: ${res.status} (${url})`);
         const { instance } = await WebAssembly.instantiateStreaming(res, {});
-        this._wasm = instance.exports;
-        this._mem = instance.exports.memory;
+        this._wasm = asAlbexExports(instance.exports);
+        this._mem = this._wasm.memory;
         this._wasm.init();
+        // Subscribe to environmental signals. Cheap and benign in node tests
+        // (the manager tolerates missing globals).
+        const rm = getResourceManager();
+        await rm.start();
+        this._resources = rm.state;
+        this._unsubscribeResources = rm.on(s => { this._resources = s; });
+        // Lazily initialise the GPU Bloom accelerator. We don't acquire a device
+        // here yet — that happens on the first search that crosses the threshold.
+        // This keeps cold-start cost the same on GPU and CPU paths.
+        if (this._opts.gpu !== 'off') {
+            this._gpu = new BloomGpu();
+        }
+    }
+    /**
+     * Decide which `.wasm` binary to fetch. Order of precedence:
+     *   1. `opts.wasmUrl` if provided — used verbatim.
+     *   2. `opts.tier` if explicit — joined with `wasmBaseUrl`.
+     *   3. `opts.wasmBaseUrl` + tier picked from the device profile.
+     *
+     * Order of precedence:
+     *   1. `opts.wasmUrl` literal               → use verbatim
+     *   2. `opts.wasmBaseUrl` + tier suffix     → fetched from that directory
+     *   3. zero-config default                  → `albex_wasm_bg.wasm` packaged
+     *                                             next to this file, resolved
+     *                                             via `import.meta.url`
+     *
+     * The zero-config default loads the std-baseline binary. Tier auto-detection
+     * is only active when `wasmBaseUrl` is given, because picking a tier in
+     * runtime would defeat any bundler's static asset rewriting. Users who want
+     * tier optimisation must serve the six variants themselves and pass the
+     * directory through `wasmBaseUrl`.
+     */
+    async _resolveWasmUrl() {
+        const o = this._opts;
+        if (o.wasmUrl) {
+            this._profile = await detectProfile();
+            return o.wasmUrl;
+        }
+        // Always cache the profile so GPU/worker decisions later don't re-probe.
+        const profile = await detectProfile();
+        this._profile = profile;
+        // Path 3: zero-config — bundler-friendly default. `new URL(..., import.meta.url)`
+        // is recognised by Vite, Webpack 5+, esbuild, Rollup, Parcel 2 and Next.js
+        // as an asset reference. They copy the .wasm to the output directory and
+        // rewrite the URL automatically. Consumers who use one of those bundlers
+        // get a working `new AlbexEngine()` with no manual setup.
+        // 0.5.0+: two main binaries only — baseline and SIMD. The tier
+        // system is gone (audit 4.1). Selection collapses to a single
+        // boolean: SIMD on or off, decided either by the explicit `simd`
+        // option or by a runtime probe.
+        const simd = o.simd === 'on'
+            ? true
+            : o.simd === 'off'
+                ? false
+                : !!profile?.wasm.simd;
+        this._simd = simd;
+        this._tier = 'std';
+        if (!o.wasmBaseUrl) {
+            // Zero-config: bundler resolves the .wasm next to dist/. We only
+            // ship the baseline alias (albex_wasm_bg.wasm) inside the npm
+            // package; integrators who want SIMD must serve both binaries
+            // themselves via `wasmBaseUrl`.
+            return new URL('../wasm/pkg/albex_wasm_bg.wasm', import.meta.url).href;
+        }
+        const base = o.wasmBaseUrl.replace(/\/+$/, '');
+        return simd ? `${base}/albex_wasm_simd.wasm` : `${base}/albex_wasm.wasm`;
+    }
+    /** The tier that was actually loaded. `null` until `init()` resolves. */
+    get tier() { return this._tier; }
+    /** True if the SIMD-accelerated binary was loaded. */
+    get simdEnabled() { return this._simd; }
+    /** True if a WebGPU device is acquired and the next search will use it. */
+    get gpuEngaged() { return !!this._gpu?.available; }
+    // ── GPU acceleration (CD1) ───────────────────────────────────────────────
+    /**
+     * Decide whether to use the GPU pre-filter for the upcoming search.
+     *
+     * Policy:
+     *  - `gpu: 'off'`             → never.
+     *  - `gpu: 'on'`              → always try (still fails over to CPU).
+     *  - `gpu: 'auto'` (default)  → only when WebGPU is available AND
+     *                                chunk count crosses `gpuThreshold`.
+     */
+    _shouldEngageGpu() {
+        const o = this._opts;
+        if (!this._gpu)
+            return false;
+        if (o.gpu === 'off')
+            return false;
+        if (o.gpu === 'on')
+            return true;
+        if (!this._profile)
+            return false;
+        const threshold = o.gpuThreshold ?? 20_000;
+        return shouldUseGpu(this._profile, this._wasm.getChunkCount(), threshold);
+    }
+    /**
+     * Run the GPU Bloom scan and install the resulting candidate bitset into
+     * WASM. The next `searchBegin` will see the mask and `searchSlice` will
+     * restrict its Bitap pass to those candidates.
+     *
+     * No-op if the GPU device hasn't been acquired yet — first call attempts
+     * `init()` lazily; if that fails, the candidate path is permanently
+     * disabled for this engine instance.
+     */
+    async _gpuPreFilter(wasmQuery) {
+        const gpu = this._gpu;
+        if (!gpu)
+            return;
+        if (!gpu.available) {
+            const ok = await gpu.init();
+            if (!ok) {
+                this._gpu = null;
+                return;
+            }
+        }
+        const chunkCount = this._wasm.getChunkCount();
+        if (chunkCount === 0)
+            return;
+        // Upload blooms if the corpus changed. We re-upload everything on any
+        // delta; incremental delta-upload is a future optimisation.
+        if (chunkCount !== this._gpuChunkCountUploaded) {
+            const ptr = this._wasm.getChunksPtr();
+            const stride = this._wasm.getChunkStructSize();
+            const bytes = new Uint8Array(this._mem.buffer, ptr, chunkCount * stride);
+            const blooms = packBloomsFromChunks(bytes, chunkCount);
+            gpu.uploadChunkBlooms(blooms, chunkCount);
+            this._gpuChunkCountUploaded = chunkCount;
+        }
+        // Build the pattern Bloom on the JS side: same hash as Rust
+        // (`c & 0x3F` after accent-folding), aggregated across all tokens.
+        const patternBloom = computePatternBloom(wasmQuery);
+        const passes = await gpu.scan(Number(patternBloom & 0xffffffffn), Number((patternBloom >> 32n) & 0xffffffffn));
+        // Push the bitset back into WASM via the scratchpad.
+        const passBytes = new Uint8Array(passes.buffer, passes.byteOffset, passes.byteLength);
+        this._writePad(passBytes);
+        this._wasm.setCandidateMask(passBytes.byteLength);
     }
     // ── Internal helpers ──────────────────────────────────────────────────────
     _u8(off, n) {
@@ -210,7 +686,7 @@ export class AlbexEngine {
     _writePad(b) {
         const ptr = this._wasm.getBuffer(b.length);
         if (!ptr)
-            throw new Error('Scratchpad too small for this chunk');
+            throw new AlbexCapacityError(`Scratchpad too small for ${b.length} bytes`);
         this._u8(ptr, b.length).set(b);
         return ptr;
     }
@@ -231,38 +707,81 @@ export class AlbexEngine {
             this._wasm.feedText(c.length);
         }
     }
+    /**
+     * Compute the FNV-1a 64-bit content hash of `bytes` via the WASM
+     * streaming API. Returns a 16-character hex string identical in shape
+     * to what the TS implementation in 0.3.x returned, so all callers
+     * stay unchanged. Single source of truth — same hash whether we use
+     * it for indexFile dedup, for snapshot v2 persistence, or anywhere
+     * else. Large inputs are chunked at FEED_SIZE just like _feedText.
+     */
+    _contentHash(bytes) {
+        const w = this._wasm;
+        w.hashBegin();
+        for (let i = 0; i < bytes.length; i += FEED_SIZE) {
+            const c = bytes.subarray(i, i + FEED_SIZE);
+            this._writePad(c);
+            w.hashFeed(c.length);
+        }
+        w.hashFinish();
+        // Read 8 result bytes back from scratchpad[0..8].
+        const ptr = w.getBuffer(8);
+        const out = this._u8(ptr, 8);
+        // Big-endian to hex. Same layout as the old hexHi + hexLo output:
+        // high u32 first (4 bytes), low u32 second (4 bytes).
+        let s = '';
+        for (let i = 0; i < 8; i++) {
+            s += out[i].toString(16).padStart(2, '0');
+        }
+        return s;
+    }
     _feedXmlBytes(xml, fn) {
+        const feeder = this._wasm[fn];
         for (let i = 0; i < xml.length; i += FEED_SIZE) {
             const c = xml.subarray(i, i + FEED_SIZE);
             this._writePad(c);
-            this._wasm[fn](c.length);
+            feeder(c.length);
         }
     }
     // ── PDF WASM (lazy load) ─────────────────────────────────────────────────
     async _ensurePdfWasm() {
         if (this._pdfWasm)
             return;
-        if (!this._opts.pdfWasmUrl)
-            throw new Error('pdfWasmUrl not set in AlbexOptions');
-        const res = await fetch(this._opts.pdfWasmUrl);
+        // Zero-config default: resolve relative to this module so bundlers copy
+        // the .wasm to the output automatically. Override with `opts.pdfWasmUrl`
+        // when serving from a separate CDN.
+        const pdfUrl = this._opts.pdfWasmUrl
+            ?? new URL('../wasm/pkg/albex_pdf.wasm', import.meta.url).href;
+        // Network politeness: on constrained connections (slow-2g/2g/saveData)
+        // we still fetch on explicit user request — `_ensurePdfWasm` is only
+        // called when the user actually drops a PDF — but we issue a console
+        // hint so embedders can surface a "this will download ~1 MB" prompt.
+        if (this._resources?.constrainedNetwork) {
+            this._diag({
+                kind: 'info', stage: 'network',
+                message: 'Downloading PDF WASM (~1 MB) on a constrained network connection',
+            });
+        }
+        const res = await fetch(pdfUrl);
         if (!res.ok)
-            throw new Error(`Failed to fetch PDF WASM: ${res.status}`);
-        const imports = makePdfWasmImports(() => this._pdfMem);
-        const { instance } = await WebAssembly.instantiateStreaming(res, imports);
-        this._pdfWasm = instance.exports;
-        this._pdfMem = instance.exports.memory;
+            throw new AlbexInitError(`Failed to fetch PDF WASM: ${res.status}`);
+        // Compile first so we can inspect the module's required imports and
+        // resolve mangled wasm-bindgen names by prefix rather than by hash.
+        const module = await WebAssembly.compileStreaming(res);
+        const imports = makePdfWasmImports(module, () => this._pdfMem);
+        const instance = await WebAssembly.instantiate(module, imports);
+        this._pdfWasm = asAlbexPdfExports(instance.exports);
+        this._pdfMem = this._pdfWasm.memory;
     }
     // ── Indexers ──────────────────────────────────────────────────────────────
-    async _indexDocx(file) {
-        const bytes = new Uint8Array(await file.arrayBuffer());
+    async _indexDocx(file, bytes) {
         const xml = await findZipEntry(bytes, 'word/document.xml');
         this._wasm.setDocumentName(this._writeStr(file.name));
         this._wasm.beginDocument();
         this._feedXmlBytes(xml, 'feedXmlBytes');
         return this._wasm.endDocument();
     }
-    async _indexXlsx(file) {
-        const bytes = new Uint8Array(await file.arrayBuffer());
+    async _indexXlsx(file, bytes) {
         this._wasm.setDocumentName(this._writeStr(file.name));
         this._wasm.beginXlsx();
         try {
@@ -280,40 +799,291 @@ export class AlbexEngine {
         }
         return this._wasm.endDocument();
     }
-    async _indexPdf(file) {
+    async _indexPdf(file, bytes) {
         await this._ensurePdfWasm();
-        const pw = this._pdfWasm;
-        const pm = this._pdfMem;
-        const bytes = new Uint8Array(await file.arrayBuffer());
+        let pw = this._pdfWasm;
+        let pm = this._pdfMem;
+        if (!pw || !pm)
+            throw new AlbexInitError('PDF WASM not initialised');
+        // Reserve input buffer and copy bytes. allocInput may trigger a
+        // memory.grow inside the PDF module; the previous pm.buffer would
+        // become detached. Refresh the memory reference before constructing
+        // the view to be safe.
         const inPtr = pw.allocInput(bytes.length);
+        pm = pw.memory;
         new Uint8Array(pm.buffer, inPtr, bytes.length).set(bytes);
-        const pageCount = pw.extractPdf(bytes.length);
+        // extractPdf can panic inside pdf-extract/lopdf for PDFs that other
+        // tools accept (encrypted streams without password, exotic font
+        // dictionaries, malformed cross-reference tables, etc.). The crate
+        // is built with panic="abort" (required on wasm32-unknown-unknown
+        // — no unwinding), so the panic surfaces as a WASM `unreachable`
+        // trap and the module instance becomes unusable.
+        //
+        // Recovery strategy when this happens:
+        //   1. Discard the poisoned instance.
+        //   2. If OCR is wired AND the rebuilt binary supports image
+        //      extraction, re-instantiate, reload the input bytes, and try
+        //      the lopdf-only image-extraction path. lopdf is a separate
+        //      parser from pdf-extract's text codec — there are real PDFs
+        //      that pdf-extract trips on but lopdf walks fine, and we can
+        //      recover the page images even when we cannot recover the
+        //      vector text.
+        //   3. If OCR isn't wired (or the recovery also fails), surface a
+        //      helpful AlbexParseError that points the user at the fix.
+        let pageCount;
+        try {
+            pageCount = pw.extractPdf(bytes.length);
+        }
+        catch (e) {
+            this._pdfWasm = null;
+            this._pdfMem = null;
+            const msg = e instanceof Error ? e.message : String(e);
+            // Try the OCR fallback before giving up.
+            if (this.ocrImage) {
+                const recovered = await this._indexPdfViaImagesOnly(file, bytes, msg);
+                if (recovered !== null)
+                    return recovered;
+            }
+            throw new AlbexParseError('pdf', `PDF text extractor crashed (${msg}). ` +
+                (this.ocrImage
+                    ? 'OCR fallback also could not recover any content from this file.'
+                    : 'Enable OCR via @albex/ocr to attempt image-based extraction as a fallback.'));
+        }
+        // Refresh memory once more — extractPdf can grow it too.
+        pm = pw.memory;
         this._wasm.setDocumentName(this._writeStr(file.name));
         this._wasm.beginDocument();
         if (pageCount === -2) {
-            // Image-only PDF — register doc with zero chunks.
+            // Image-only (scanned) PDF. If OCR is wired AND the PDF binary
+            // supports image extraction, fall through to the scanned-PDF path.
+            // Otherwise keep today's behaviour: register the doc with 0 chunks
+            // so the user sees the file in the index but searches won't hit it.
+            const supportsImages = typeof pw.extractPageImages === 'function'
+                && typeof pw.getPageCount === 'function';
+            if (this.ocrImage && supportsImages) {
+                await this._indexPdfScanned(pw);
+            }
             return this._wasm.endDocument();
         }
         if (pageCount < 0) {
             const errLen = pw.getErrorLen();
             const errPtr = pw.getErrorPtr();
             const msg = errLen > 0
-                ? new TextDecoder().decode(new Uint8Array(pm.buffer, errPtr, errLen))
+                ? _dec.decode(new Uint8Array(pm.buffer, errPtr, errLen))
                 : 'PDF parse error';
-            throw new Error(msg);
+            throw new AlbexParseError('pdf', msg);
         }
         for (let p = 0; p < pageCount; p++) {
             const len = pw.getPageLen(p);
             if (!len)
                 continue;
-            const text = new TextDecoder('utf-8').decode(new Uint8Array(pm.buffer, pw.getPagePtr(p), len));
+            // Re-read memory each iteration — feedText writes into the main
+            // WASM, but reading the PDF page pointers requires the live PDF
+            // memory which may have been grown by intermediate calls.
+            const liveMem = pw.memory;
+            const text = _dec.decode(new Uint8Array(liveMem.buffer, pw.getPagePtr(p), len));
             this._feedText(text);
             this._wasm.flushParagraph();
         }
+        // Hybrid OCR pass: when the OCR adapter is wired with
+        // `options.alwaysExtractEmbeddedImages: true`, also walk every page
+        // for embedded images and OCR them on top of the vector text.
+        if (this._ocrAdapter
+            && this._ocrAdapter.options?.alwaysExtractEmbeddedImages
+            && typeof pw.extractPageImages === 'function'
+            && typeof pw.getPageCount === 'function') {
+            const totalPages = pw.getPageCount();
+            for (let p = 0; p < totalPages; p++) {
+                const ocrText = await this._ocrPageEmbeddedImages(pw, p);
+                if (ocrText === null)
+                    break; // WASM trapped, stop hybrid pass.
+                if (ocrText) {
+                    this._feedText(ocrText);
+                    this._wasm.flushParagraph();
+                }
+            }
+        }
+        return this._wasm.endDocument();
+    }
+    /**
+     * Scanned-PDF OCR fallback. Called from `_indexPdf` when `extractPdf`
+     * returns `-2` (image-only PDF) AND `@albex/ocr` has been wired via
+     * `enableOcr(engine)`.
+     *
+     * Walks every page of the PDF, extracts embedded JPEG / JPEG2000 image
+     * XObjects, runs each through `engine.ocrImage`, and feeds the recognised
+     * text into the index — one paragraph per page so search snippets stay
+     * tied to the page they came from.
+     *
+     * Failure modes handled here (none re-thrown — the goal is best-effort
+     * indexing, not all-or-nothing):
+     *
+     *   * A page's `extractPageImages` traps the WASM instance: the instance
+     *     is discarded so the next PDF starts fresh, and we stop iterating
+     *     (no more pages can be read from a poisoned instance). The doc is
+     *     still committed with whatever text we got from earlier pages.
+     *   * An individual image fails to OCR (Tesseract decode error, JP2 not
+     *     supported in this browser, etc.): we skip that image and keep
+     *     going. Partial coverage beats nothing.
+     *   * A page yields no extractable images (e.g. uses Flate/CCITT/JBIG2):
+     *     no paragraph is emitted; the page contributes 0 chunks.
+     */
+    async _indexPdfScanned(pw) {
+        if (!this.ocrImage)
+            return;
+        const totalPages = pw.getPageCount();
+        if (!totalPages)
+            return;
+        for (let p = 0; p < totalPages; p++) {
+            const pageText = await this._ocrPageEmbeddedImages(pw, p);
+            if (pageText === null)
+                return; // WASM poisoned mid-iteration.
+            if (pageText) {
+                this._feedText(pageText);
+                this._wasm.flushParagraph();
+            }
+        }
+    }
+    /**
+     * Walk one page's embedded image XObjects, OCR each image, and return
+     * the joined recognised text for that page.
+     *
+     * Used by:
+     *   - `_indexPdfScanned`: image-only PDFs (extractPdf returned -2).
+     *   - `_indexPdf` hybrid path: when `ocrConfig.alwaysExtractEmbeddedImages`
+     *     is set, every page goes through here on top of the normal text
+     *     extraction.
+     *
+     * Returns:
+     *   - The recognised text (possibly empty if the page has no qualifying
+     *     images or every OCR call failed).
+     *   - `null` if the PDF WASM trapped during extractPageImages — the
+     *     caller should abort the remaining pages because the instance is
+     *     now poisoned.
+     *
+     * Failure-handling philosophy: best-effort. An OCR failure on one image
+     * does not stop the page; a page with no images does not stop the doc;
+     * only a WASM trap stops the doc.
+     */
+    async _ocrPageEmbeddedImages(pw, page) {
+        const ocr = this.ocrImage;
+        if (!ocr)
+            return '';
+        let imageCount;
+        try {
+            imageCount = pw.extractPageImages(page);
+        }
+        catch (e) {
+            // The PDF module just trapped — it is now poisoned. Drop our refs
+            // so `_ensurePdfWasm` re-instantiates on the next call.
+            this._pdfWasm = null;
+            this._pdfMem = null;
+            this._diag({
+                kind: 'skipped', stage: 'pdf', page: page + 1,
+                message: `PDF image extractor trapped: ${e instanceof Error ? e.message : String(e)}. Remaining pages skipped.`,
+            });
+            return null;
+        }
+        if (imageCount <= 0)
+            return '';
+        // The buffer view must be re-acquired AFTER extractPageImages —
+        // it may have grown the linear memory and detached old views.
+        const liveMem = pw.memory;
+        let pageText = '';
+        for (let i = 0; i < imageCount; i++) {
+            const len = pw.getPageImageLen(i);
+            if (!len)
+                continue;
+            const ptr = pw.getPageImagePtr(i);
+            const kind = pw.getPageImageKind(i);
+            const mime = kind === 1 ? 'image/jpeg'
+                : kind === 2 ? 'image/jp2'
+                    : 'application/octet-stream';
+            // Snapshot the image bytes into a fresh ArrayBuffer. The pointer
+            // returned by getPageImagePtr is only valid until the next
+            // extractPageImages / extractPdf call, so we cannot hold the view.
+            const copy = new Uint8Array(len);
+            copy.set(new Uint8Array(liveMem.buffer, ptr, len));
+            const blob = new Blob([copy.buffer], { type: mime });
+            try {
+                const { text } = await ocr(blob);
+                const trimmed = text?.trim();
+                if (trimmed) {
+                    pageText = pageText ? `${pageText} ${trimmed}` : trimmed;
+                }
+            }
+            catch (e) {
+                // Image-level OCR failure — skip and continue. JP2 in browsers
+                // without native support lands here; so do truncated or
+                // unsupported JPEG variants. Worker aborts (Tesseract.js
+                // "Aborted(-1)") are also caught here; if they bypass the
+                // promise rejection and surface as `uncaught` instead, the
+                // demo's window.onerror handler will keep the app alive.
+                this._diag({
+                    kind: 'skipped', stage: 'ocr', page: page + 1,
+                    message: `OCR failed on image ${i + 1}: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+        }
+        return pageText;
+    }
+    /**
+     * Last-chance OCR path used when `extractPdf` itself trapped (pdf-extract
+     * crashed but lopdf may still be able to walk the file). Re-instantiates
+     * the PDF WASM, reloads the input bytes, and tries the image-extraction
+     * route directly — bypassing the text codec entirely.
+     *
+     * Returns:
+     *   * the doc's chunk count on success (even 0 — that means lopdf could
+     *     parse but no qualifying images existed, which still beats a hard
+     *     parse error),
+     *   * null if the recovery itself failed (binary lacks the image exports,
+     *     re-instantiation failed, or lopdf also trapped). In the null case
+     *     the caller throws AlbexParseError so the user sees a clear message.
+     */
+    async _indexPdfViaImagesOnly(file, bytes, originalError) {
+        try {
+            await this._ensurePdfWasm();
+        }
+        catch {
+            return null;
+        }
+        const pw = this._pdfWasm;
+        if (!pw)
+            return null;
+        const supportsImages = typeof pw.extractPageImages === 'function'
+            && typeof pw.getPageCount === 'function';
+        if (!supportsImages)
+            return null;
+        // Reload input bytes into the fresh instance. allocInput may grow the
+        // memory, so re-acquire the buffer view immediately after.
+        let inPtr;
+        try {
+            inPtr = pw.allocInput(bytes.length);
+            new Uint8Array(pw.memory.buffer, inPtr, bytes.length).set(bytes);
+        }
+        catch (e) {
+            this._diag({
+                kind: 'skipped', stage: 'pdf',
+                message: `PDF re-load after extractor crash failed: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            return null;
+        }
+        // Set up the doc and let _indexPdfScanned do the page-by-page walk.
+        // _indexPdfScanned tolerates lopdf failing mid-stream — it caches the
+        // poisoned instance and returns early. If lopdf trips on the very
+        // first page, no paragraphs are emitted and we end up with 0 chunks.
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        this._diag({
+            kind: 'fallback', stage: 'pdf', file: file.name,
+            message: `pdf-extract failed (${originalError}); attempting OCR-only fallback via lopdf`,
+        });
+        await this._indexPdfScanned(pw);
         return this._wasm.endDocument();
     }
-    async _indexTxt(file) {
-        const text = await file.text();
+    async _indexTxt(file, bytes) {
+        const text = _dec.decode(bytes);
         this._wasm.setDocumentName(this._writeStr(file.name));
         this._wasm.beginDocument();
         for (const para of text.split(/\n{2,}/)) {
@@ -325,8 +1095,8 @@ export class AlbexEngine {
         }
         return this._wasm.endDocument();
     }
-    async _indexXml(file) {
-        const plain = (await file.text())
+    async _indexXml(file, bytes) {
+        const plain = _dec.decode(bytes)
             .replace(/<[^]*?>/g, '\n')
             .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
             .replace(/&quot;/g, '"').replace(/&apos;/g, "'")
@@ -342,54 +1112,804 @@ export class AlbexEngine {
         }
         return this._wasm.endDocument();
     }
+    // ── Markdown ─────────────────────────────────────────────────────────────
+    // Strip CommonMark inline marks but keep word content. Paragraphs split on
+    // blank lines, same convention as TXT/XML.
+    async _indexMd(file, bytes) {
+        const text = _dec.decode(bytes)
+            // Remove fenced code blocks entirely (often noisy for search relevance).
+            .replace(/```[\s\S]*?```/g, '\n')
+            .replace(/~~~[\s\S]*?~~~/g, '\n')
+            // Strip ATX heading markers but keep heading text.
+            .replace(/^#{1,6}\s+/gm, '')
+            // Replace inline links/images with their visible text.
+            .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+            .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+            // Strip emphasis markers (preserve content).
+            .replace(/(\*\*|__|\*|_)/g, '')
+            // Inline code.
+            .replace(/`([^`]+)`/g, '$1')
+            // Blockquote marks.
+            .replace(/^>\s?/gm, '')
+            // List markers.
+            .replace(/^\s*[-*+]\s+/gm, '')
+            .replace(/^\s*\d+\.\s+/gm, '');
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        for (const para of text.split(/\n{2,}/)) {
+            const l = para.replace(/\n/g, ' ').trim();
+            if (l) {
+                this._feedText(l);
+                this._wasm.flushParagraph();
+            }
+        }
+        return this._wasm.endDocument();
+    }
+    // ── HTML ─────────────────────────────────────────────────────────────────
+    // Strip <script>/<style> entire blocks, then drop tag markup. The output is
+    // chunked at <p>, <br>, <h*>, <li>, <tr> boundaries (mapped to paragraph
+    // breaks) so search location numbers map naturally to the document outline.
+    async _indexHtml(file, bytes) {
+        const html = _dec.decode(bytes)
+            .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
+            .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
+            // Treat block-level closers as paragraph separators.
+            .replace(/<\/(p|h[1-6]|li|tr|div|section|article|header|footer)\s*>/gi, '\n\n')
+            .replace(/<br\s*\/?\s*>/gi, '\n')
+            // Drop remaining tags.
+            .replace(/<[^>]+>/g, ' ')
+            // Decode common entities (full set would need a table; this covers >95%).
+            .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&nbsp;/g, ' ')
+            .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+            .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+            .replace(/[ \t]+/g, ' ');
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        for (const para of html.split(/\n{2,}/)) {
+            const l = para.replace(/\n/g, ' ').trim();
+            if (l) {
+                this._feedText(l);
+                this._wasm.flushParagraph();
+            }
+        }
+        return this._wasm.endDocument();
+    }
+    // ── JSON ─────────────────────────────────────────────────────────────────
+    // Extract every string value (keys + leaf strings) recursively. Each leaf
+    // becomes its own searchable chunk via paragraph flush. Numbers/booleans
+    // are skipped (cannot match a textual query usefully).
+    async _indexJson(file, bytes) {
+        let root;
+        try {
+            root = JSON.parse(_dec.decode(bytes));
+        }
+        catch (e) {
+            throw new AlbexParseError('json', e.message);
+        }
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        const visit = (v) => {
+            if (typeof v === 'string') {
+                if (v.trim()) {
+                    this._feedText(v);
+                    this._wasm.flushParagraph();
+                }
+            }
+            else if (Array.isArray(v)) {
+                for (const x of v)
+                    visit(x);
+            }
+            else if (v && typeof v === 'object') {
+                for (const [k, x] of Object.entries(v)) {
+                    if (k.trim()) {
+                        this._feedText(k);
+                        this._wasm.flushParagraph();
+                    }
+                    visit(x);
+                }
+            }
+        };
+        visit(root);
+        return this._wasm.endDocument();
+    }
+    // ── CSV ──────────────────────────────────────────────────────────────────
+    // RFC 4180 lite: comma-separated, optional double quotes, escaped "" inside
+    // quoted fields. Each row becomes one paragraph (location = row index, with
+    // header row at location 0).
+    async _indexCsv(file, bytes) {
+        // Strip an optional UTF-8 BOM. Excel writes it by default for "CSV UTF-8";
+        // without this fix the first field of the first row would start with
+        // U+FEFF, which both shifts column alignment when consumers split on a
+        // field name and breaks search hits on "Subject" / "Asunto" etc.
+        let text = _dec.decode(bytes);
+        if (text.charCodeAt(0) === 0xFEFF)
+            text = text.slice(1);
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        let row = [];
+        let field = '';
+        let inQuoted = false;
+        const flushRow = () => {
+            const line = row.join(' ').trim();
+            if (line) {
+                this._feedText(line);
+                this._wasm.flushParagraph();
+            }
+            row = [];
+        };
+        for (let i = 0; i < text.length; i++) {
+            const c = text[i];
+            if (inQuoted) {
+                if (c === '"') {
+                    if (text[i + 1] === '"') {
+                        field += '"';
+                        i++;
+                    }
+                    else
+                        inQuoted = false;
+                }
+                else
+                    field += c;
+            }
+            else {
+                if (c === ',') {
+                    row.push(field);
+                    field = '';
+                }
+                else if (c === '\n') {
+                    row.push(field);
+                    field = '';
+                    flushRow();
+                }
+                else if (c === '\r') { /* skip */ }
+                else if (c === '"' && field.length === 0)
+                    inQuoted = true;
+                else
+                    field += c;
+            }
+        }
+        if (field.length > 0 || row.length > 0) {
+            row.push(field);
+            flushRow();
+        }
+        return this._wasm.endDocument();
+    }
+    // ── EML / MBOX ───────────────────────────────────────────────────────────
+    // Minimal MIME: parse the first text/plain body. Headers From/To/Subject
+    // are indexed as separate paragraphs so they're individually searchable.
+    //
+    // What's decoded:
+    //   * Content-Transfer-Encoding: base64       → decoded.
+    //   * Content-Transfer-Encoding: quoted-printable → decoded.
+    //   * Content-Transfer-Encoding: 7bit / 8bit  → pass-through.
+    //   * Nested multipart (multipart/alternative inside multipart/mixed) by
+    //     recursively walking boundaries until a text/plain section is found.
+    //
+    // What's not decoded (out of scope for this "lite" parser):
+    //   * Encoded-word headers (=?utf-8?Q?...?=) — only the raw bytes go in.
+    //   * Charset conversions other than UTF-8 — assumes the body decodes as UTF-8.
+    //   * HTML-only emails — they're dropped if no text/plain part is present.
+    //   * MBOX format (multiple emails concatenated). Each email needs to be
+    //     fed separately.
+    async _indexEml(file, bytes) {
+        const raw = _dec.decode(bytes).replace(/\r\n/g, '\n');
+        const headerEnd = raw.indexOf('\n\n');
+        const headersBlock = headerEnd > 0 ? raw.slice(0, headerEnd) : raw;
+        const body = headerEnd > 0 ? raw.slice(headerEnd + 2) : '';
+        const header = (block, name) => {
+            const m = new RegExp(`^${name}:\\s*(.+(?:\\n[ \\t].+)*)`, 'mi').exec(block);
+            return m ? (m[1] ?? '').replace(/\n[ \t]+/g, ' ').trim() : '';
+        };
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        const subj = header(headersBlock, 'Subject');
+        const from = header(headersBlock, 'From');
+        const to = header(headersBlock, 'To');
+        for (const h of [subj, from, to]) {
+            if (h) {
+                this._feedText(h);
+                this._wasm.flushParagraph();
+            }
+        }
+        const plain = this._extractEmlTextPlain(headersBlock, body, header) ?? body;
+        for (const para of plain.split(/\n{2,}/)) {
+            const l = para.replace(/\n/g, ' ').trim();
+            if (l) {
+                this._feedText(l);
+                this._wasm.flushParagraph();
+            }
+        }
+        return this._wasm.endDocument();
+    }
+    /**
+     * Walk the multipart tree until a text/plain section is found. Returns
+     * the decoded body as a string, or null if no text/plain part exists.
+     *
+     * The function is called with the headers and body of the *current*
+     * MIME entity (the top-level message at first, then each multipart child
+     * on recursion). For single-part entities it inspects the entity's own
+     * Content-Transfer-Encoding and decodes accordingly.
+     */
+    _extractEmlTextPlain(headersBlock, body, header) {
+        const contentType = header(headersBlock, 'Content-Type');
+        const boundary = /boundary="?([^";]+)"?/i.exec(contentType)?.[1];
+        if (!boundary) {
+            // Single-part body. If it claims to be text/plain (the default when
+            // Content-Type is absent), apply Transfer-Encoding decoding here.
+            // Anything else (text/html, application/*) gets returned raw — the
+            // top-level caller still feeds it as text, but searches against
+            // genuinely binary payloads will not hit anything useful.
+            if (contentType === '' || /text\/plain/i.test(contentType)) {
+                return decodeEmlBody(headersBlock, body, header);
+            }
+            return body;
+        }
+        const parts = body.split(`--${boundary}`);
+        for (const part of parts) {
+            const trimmed = part.replace(/^\n+/, '');
+            const ph = trimmed.indexOf('\n\n');
+            if (ph < 0)
+                continue;
+            const partHeaders = trimmed.slice(0, ph);
+            const partBody = trimmed.slice(ph + 2);
+            const partCtype = header(partHeaders, 'Content-Type');
+            if (/^multipart\//i.test(partCtype)) {
+                const inner = this._extractEmlTextPlain(partHeaders, partBody, header);
+                if (inner)
+                    return inner;
+                continue;
+            }
+            if (/text\/plain/i.test(partCtype)) {
+                return decodeEmlBody(partHeaders, partBody, header);
+            }
+        }
+        return null;
+    }
+    // ── RTF ──────────────────────────────────────────────────────────────────
+    //
+    // Strip the {\rtf1...} group structure. Control words (\xxx and \xxxN),
+    // hex escapes (\'XX), unicode escapes (\uN ?) and groups are processed;
+    // plain runs are kept.
+    //
+    // Character decoding:
+    //   * \'XX  → Windows-1252 byte XX. RTF defaults to cp1252 for high-ANSI;
+    //             we map the relevant rows (0x80–0x9F differs from Latin-1)
+    //             to their Unicode equivalents. Outside that block, the byte
+    //             is taken as Latin-1 (which equals Unicode below 0x100).
+    //             Result: accents in es/fr/de/it/pt RTF dumps survive.
+    //   * \uN ? → Unicode codepoint N (signed 16-bit, negative means N+65536).
+    //             Followed by a fallback character which we then skip — Word
+    //             writes the ASCII transliteration of the unicode glyph as a
+    //             fallback for non-Unicode readers; we ignore it because we
+    //             have the real codepoint.
+    //   * \-   → soft hyphen (drop).
+    //   * \~   → non-breaking space.
+    //   * \emdash, \endash, \bullet, \lquote, \rquote, \ldblquote, \rdblquote
+    //             → their Unicode equivalents.
+    //
+    // What's not handled (assumes Word/Pages/LibreOffice output, where
+    // these aren't load-bearing):
+    //   * \ansicpg, \fcharset — we always assume cp1252 for \' escapes.
+    //   * \bin — binary data with explicit length; rare in document RTF.
+    //   * Field codes — rendered as the visible text (good enough for search).
+    async _indexRtf(file, bytes) {
+        const src = _dec.decode(bytes);
+        let out = '';
+        let i = 0;
+        let depth = 0;
+        // Track if we're inside a destination group we should skip (e.g. \fonttbl).
+        let skipDepth = 0;
+        const SKIP_DESTINATIONS = /^\\(fonttbl|colortbl|stylesheet|info|pict|object|header|footer)\b/;
+        while (i < src.length) {
+            const c = src[i];
+            if (c === '{') {
+                depth++;
+                i++;
+                continue;
+            }
+            if (c === '}') {
+                depth--;
+                if (skipDepth > 0 && depth < skipDepth)
+                    skipDepth = 0;
+                i++;
+                continue;
+            }
+            if (c === '\\') {
+                // Hex byte escape: \'XX
+                if (src[i + 1] === '\'' && i + 3 < src.length) {
+                    const hex = src.slice(i + 2, i + 4);
+                    if (/^[0-9A-Fa-f]{2}$/.test(hex)) {
+                        if (skipDepth === 0)
+                            out += rtfCp1252ToChar(parseInt(hex, 16));
+                        i += 4;
+                        continue;
+                    }
+                    // Malformed — drop and advance.
+                    i += 2;
+                    continue;
+                }
+                // Unicode escape: \uN followed by optional fallback character.
+                // N is signed 16-bit per the spec; negative values mean N + 65536.
+                const um = /^\\u(-?\d+) ?/.exec(src.slice(i));
+                if (um) {
+                    let code = parseInt(um[1] ?? '0', 10);
+                    if (code < 0)
+                        code += 0x10000;
+                    if (skipDepth === 0 && code > 0 && code < 0x110000) {
+                        out += String.fromCodePoint(code);
+                    }
+                    i += um[0].length;
+                    // Skip the fallback char. Word writes one ASCII char after \uN
+                    // (the "uc1" count). We assume uc1, which is the Word default.
+                    if (i < src.length && src[i] !== '\\' && src[i] !== '{' && src[i] !== '}') {
+                        i++;
+                    }
+                    continue;
+                }
+                // Control word / symbol.
+                const m = /^\\([A-Za-z]+)(-?\d+)?\s?/.exec(src.slice(i));
+                if (m) {
+                    const word = m[1] ?? '';
+                    if (skipDepth === 0 && SKIP_DESTINATIONS.test(src.slice(i)))
+                        skipDepth = depth;
+                    if (skipDepth === 0) {
+                        switch (word) {
+                            case 'par':
+                            case 'line':
+                            case 'sect':
+                                out += '\n\n';
+                                break;
+                            case 'tab':
+                                out += '\t';
+                                break;
+                            case 'emdash':
+                                out += '—';
+                                break;
+                            case 'endash':
+                                out += '–';
+                                break;
+                            case 'bullet':
+                                out += '•';
+                                break;
+                            case 'lquote':
+                                out += '‘';
+                                break;
+                            case 'rquote':
+                                out += '’';
+                                break;
+                            case 'ldblquote':
+                                out += '“';
+                                break;
+                            case 'rdblquote':
+                                out += '”';
+                                break;
+                            default: /* drop other control words silently */ break;
+                        }
+                    }
+                    i += m[0].length;
+                    continue;
+                }
+                // Escaped single character: \\, \{, \}, \-, \~ etc.
+                if (skipDepth === 0) {
+                    const escaped = src[i + 1];
+                    if (escaped === '~')
+                        out += ' '; // non-breaking space
+                    else if (escaped === '-') { /* soft hyphen — drop */ }
+                    else if (escaped !== undefined)
+                        out += escaped;
+                }
+                i += 2;
+                continue;
+            }
+            if (skipDepth === 0)
+                out += c;
+            i++;
+        }
+        this._wasm.setDocumentName(this._writeStr(file.name));
+        this._wasm.beginDocument();
+        for (const para of out.split(/\n{2,}/)) {
+            const l = para.replace(/\n/g, ' ').trim();
+            if (l) {
+                this._feedText(l);
+                this._wasm.flushParagraph();
+            }
+        }
+        return this._wasm.endDocument();
+    }
+    static _INDEXERS = {
+        docx: (e, f, b) => e._indexDocx(f, b),
+        xlsx: (e, f, b) => e._indexXlsx(f, b),
+        pdf: (e, f, b) => e._indexPdf(f, b),
+        txt: (e, f, b) => e._indexTxt(f, b),
+        xml: (e, f, b) => e._indexXml(f, b),
+        md: (e, f, b) => e._indexMd(f, b),
+        markdown: (e, f, b) => e._indexMd(f, b),
+        html: (e, f, b) => e._indexHtml(f, b),
+        htm: (e, f, b) => e._indexHtml(f, b),
+        json: (e, f, b) => e._indexJson(f, b),
+        csv: (e, f, b) => e._indexCsv(f, b),
+        eml: (e, f, b) => e._indexEml(f, b),
+        rtf: (e, f, b) => e._indexRtf(f, b),
+    };
     // ── Public API ────────────────────────────────────────────────────────────
     /**
      * Index a file. Supported formats: DOCX, XLSX, PDF, TXT, XML.
      * Throws for unsupported formats or parse errors.
      */
     async indexFile(file) {
+        return this._exclusive(() => this._indexFileInner(file));
+    }
+    async _indexFileInner(file) {
         const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
         const indexer = AlbexEngine._INDEXERS[ext];
         if (!indexer)
-            throw new Error(`Unsupported format: .${ext}`);
+            throw new AlbexUnsupportedFormatError(ext);
+        // Hash the source bytes for idempotency. We always read the bytes once
+        // here so the indexer can reuse them — avoids a double File.arrayBuffer().
+        const bytes = new Uint8Array(await file.arrayBuffer());
+        const hash = this._contentHash(bytes);
+        // Idempotency: if a non-deleted doc already has this hash, return it
+        // unchanged. Cheap O(N) scan since MAX_DOCS = 128.
+        const existing = this._docs.find(d => d.contentHash === hash);
+        if (existing)
+            return existing;
+        const w = this._wasm;
         const t0 = performance.now();
-        const textPre = this._wasm.getTextUsed();
-        const chunks = await indexer(this, file);
+        const textPre = w.getTextUsed();
+        const docCountBefore = w.getDocCount();
+        // Snapshot v2: hand the content hash to the WASM so it persists with
+        // the doc. Older binaries (pre-v2) lack this export — we silently skip
+        // and behave like before. The indexer will overwrite the scratchpad
+        // immediately after (with the doc name), which is fine because
+        // setDocumentContentHash copies into pending_content_hash before
+        // returning.
+        if (typeof w.setDocumentContentHash === 'function') {
+            const hashBytes = hashHexToBytes(hash);
+            this._writePad(hashBytes);
+            w.setDocumentContentHash(hashBytes.length);
+        }
+        const chunks = await indexer(this, file, bytes);
+        // Capacity check (0.6.0). The WASM pools fill silently and break out of
+        // their ingest loops; getLastIndexOverflow reports which one filled.
+        // Surface a typed error instead of returning a half-indexed document the
+        // caller cannot tell apart from a complete one (audit finding #3).
+        const overflow = w.getLastIndexOverflow();
+        if (overflow !== 0) {
+            const which = (overflow & 1) ? 'chunks' : (overflow & 2) ? 'text'
+                : (overflow & 4) ? 'docs' : 'names';
+            const pools = [
+                overflow & 1 ? 'chunk pool' : '',
+                overflow & 2 ? 'text pool' : '',
+                overflow & 4 ? 'document table' : '',
+                overflow & 8 ? 'name pool' : '',
+            ].filter(Boolean).join(', ');
+            throw new AlbexCapacityError(`Index capacity exceeded while indexing "${file.name}" (${pools} full). ` +
+                `The document was rolled back (not indexed); treat the index as full ` +
+                `(compact(), shard across an AlbexPool, or reset()).`, which);
+        }
+        // The new doc occupies slot `docCountBefore`.
+        const docId = w.getDocId(docCountBefore);
         const doc = {
             name: file.name,
             ext,
             chunks,
             indexTimeMs: performance.now() - t0,
-            textBytes: this._wasm.getTextUsed() - textPre,
+            textBytes: w.getTextUsed() - textPre,
+            docId,
+            contentHash: hash,
         };
         this._docs.push(doc);
         return doc;
     }
+    /**
+     * Mark a previously indexed document as removed. Searches no longer return
+     * its chunks. Storage is reclaimed only after `compact()`.
+     *
+     * `id` can be the file name or the contentHash returned by `indexFile`.
+     * Returns `true` if a matching document was found and tombstoned.
+     */
+    removeDocument(id) {
+        this._assertIdle('removeDocument');
+        return this._removeDocumentInner(id);
+    }
+    _removeDocumentInner(id) {
+        const doc = this._docs.find(d => d.name === id || d.contentHash === id);
+        if (!doc)
+            return false;
+        const ok = this._wasm.removeDocument(doc.docId) === 1;
+        if (ok) {
+            this._docs = this._docs.filter(d => d !== doc);
+        }
+        return ok;
+    }
+    /**
+     * Replace a previously indexed document with new content. Equivalent to
+     * `removeDocument(name)` + `indexFile(newFile)` but does not trigger the
+     * idempotency check (so re-indexing the *same* bytes after a remove works).
+     */
+    async replaceDocument(name, newFile) {
+        return this._exclusive(async () => {
+            this._removeDocumentInner(name);
+            // Index directly via the inner path (we already hold the lock).
+            const doc = await this._indexFileInner(newFile);
+            // Repeated replaces leave tombstones in the text pool; reclaim under
+            // pressure so the pool isn't silently exhausted (audit finding #7).
+            this._autoCompactIfNeeded();
+            return doc;
+        });
+    }
+    /**
+     * Reclaim storage from previously removed documents. Compacts CHUNKS,
+     * TEXT_POOL, DOC_NAMES and NAME_POOL in place. Idempotent.
+     *
+     * Note: doc_ids of surviving documents are preserved, so any stored
+     * references (e.g. in a UI) remain valid.
+     */
+    compact() {
+        this._assertIdle('compact');
+        this._wasm.compact();
+    }
     /**
      * Search the index. Supports:
      * - Simple queries:  `contrato`  (AND of tokens, accent-insensitive)
      * - Phrase queries:  `"contrato marco"`  (must appear as phrase)
      * - OR queries:      `contrato | acuerdo`  (union of two searches)
+     *
+     * Pass `{ windowed: true }` to receive cropped snippets with ASCII ellipsis
+     * markers instead of full chunk text. Defaults: 60 bytes before, 120 after.
+     */
+    search(query, opts = {}) {
+        this._assertIdle('search');
+        const w = this._wasm;
+        const ql = this._writeStr(query);
+        const kind = w.prepareQuery(ql);
+        if (kind < 0)
+            return [];
+        if (kind === 2) {
+            // OR: iterate branches and merge in TS. WASM stores compiled
+            // branches internally so we never re-tokenize on the host.
+            return this._searchOr(query, opts);
+        }
+        w.selectQueryBranch(0);
+        // Phrase queries (kind 1) post-filter on adjacency. Pass the tokens down
+        // so the check runs against the FULL chunk text, not a cropped windowed
+        // snippet — otherwise `{ windowed: true }` could drop a valid phrase hit
+        // whose second term fell outside the window (audit finding #7).
+        const phraseTokens = kind === 1 ? this._branchTokens(0) : undefined;
+        return this._runSearch(query, opts, phraseTokens);
+    }
+    /** Read the WASM-compiled tokens of branch `i` for phrase post-filter.
+     * The bytes returned are exactly what the WASM tokenizer produced —
+     * no TS re-tokenization. */
+    _branchTokens(i) {
+        const n = this._wasm.getQueryBranchPattern(i);
+        if (n === 0)
+            return [];
+        const pattern = this._readPad(n);
+        return pattern.split(' ').filter(t => t.length > 0);
+    }
+    /**
+     * Cooperative search. Processes the corpus in slices, yielding to the
+     * event loop between them so the host UI thread keeps a chance to paint
+     * even while a long scan is in flight.
+     *
+     * NOTE: this is NOT incremental streaming. Results are materialised
+     * once the search completes and then iterated out in score-descending
+     * order. The async iterator shape is preserved because the work that
+     * produces those results genuinely yields to the scheduler between
+     * slices — a future iteration may stream individual results before the
+     * heap sorts, but doing so today would deliver them in arbitrary order.
+     *
+     * Pass `opts.frameBudgetMs` to control the slice size (default 8 ms).
+     */
+    async *searchCooperative(query, opts = {}) {
+        // Collect under the exclusivity lock so no other engine op interleaves at
+        // a slice boundary; the per-slice scheduler yields still happen inside.
+        const results = await this._exclusive(() => this._searchCooperativeCollect(query, opts));
+        for (const r of results)
+            yield r;
+    }
+    /** Materialise a cooperative search to a sorted result array. Runs inside
+     * the exclusivity lock. Frame-budget yielding lives in _runSearchBudgeted. */
+    async _searchCooperativeCollect(query, opts) {
+        const budget = opts.frameBudgetMs ?? 8;
+        const w = this._wasm;
+        const ql = this._writeStr(query);
+        const kind = w.prepareQuery(ql);
+        if (kind < 0)
+            return [];
+        if (kind === 2) {
+            // OR branches — run each as its own resumable search and merge.
+            const seen = new Set();
+            const all = [];
+            const n = w.getQueryBranchCount();
+            for (let i = 0; i < n; i++) {
+                w.selectQueryBranch(i);
+                const r = await this._runSearchBudgeted(query, opts, budget, undefined, i);
+                for (const x of r) {
+                    const key = `${x.documentName}:${x.location}:${x.matchStart}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        all.push(x);
+                    }
+                }
+            }
+            all.sort((a, b) => b.score - a.score);
+            return all;
+        }
+        w.selectQueryBranch(0);
+        const phraseTokens = kind === 1 ? this._branchTokens(0) : undefined;
+        return this._runSearchBudgeted(query, opts, budget, phraseTokens, 0);
+    }
+    /**
+     * @deprecated Renamed to `searchCooperative` in 0.3.0. The original name
+     * was misleading — this method does not stream incremental results, it
+     * yields to the scheduler between slices and returns a batch. The alias
+     * keeps existing integrations working; it will be removed in 0.4.0.
      */
-    search(query) {
-        const parsed = parseQuery(query);
-        if (parsed.kind === 'or') {
-            return this._searchOr(parsed.branches, query);
+    async *searchStream(query, opts = {}) {
+        warnSearchStreamDeprecated();
+        yield* this.searchCooperative(query, opts);
+    }
+    /**
+     * Drive a resumable search until done, yielding to the scheduler when the
+     * frame budget is exceeded. Returns the materialised result array.
+     *
+     * Heuristic: each call to `searchSlice` processes a chunk batch, then we
+     * check elapsed time. The batch size doubles up to a cap to amortise the
+     * JS<->WASM overhead on fast machines; on slow machines a single batch
+     * may eat the entire budget, which is also fine.
+     */
+    async _runSearchBudgeted(displayQuery, opts, budgetMs, phraseTokens, branchIdx = 0) {
+        const w = this._wasm;
+        // Pattern is already set by the caller via selectQueryBranch(branchIdx).
+        // Snapshot THAT branch's compiled pattern for the GPU pre-filter hash —
+        // not branch 0, which would build the wrong candidate mask for OR
+        // branches and silently drop their hits (audit finding #6).
+        const activePatternLen = w.getQueryBranchPattern(branchIdx);
+        const activePattern = activePatternLen > 0 ? this._readPad(activePatternLen) : '';
+        // GPU pre-filter (CD1). If enabled AND the corpus is large enough,
+        // the GPU computes the candidate bitset and we install it into WASM
+        // before searchBegin so the slice loop only inspects candidates.
+        // Failure here is silent: we fall back to CPU-only Bloom transparently.
+        if (this._shouldEngageGpu()) {
+            try {
+                await this._gpuPreFilter(activePattern);
+            }
+            catch (e) {
+                // Don't let a GPU hiccup kill the search — drop to CPU path.
+                this._diag({
+                    kind: 'fallback', stage: 'gpu',
+                    message: `GPU pre-filter failed; falling back to CPU: ${e instanceof Error ? e.message : String(e)}`,
+                });
+                w.clearCandidateMask();
+            }
         }
-        const results = this._runSearch(tokensToWasmQuery(parsed.tokens), query);
-        if (parsed.kind === 'phrase') {
-            return results.filter(r => containsPhrase(r.snippet, parsed.tokens));
+        const t0 = performance.now();
+        if (w.searchBegin() === 0) {
+            this._lastSearch = {
+                query: displayQuery, timeMs: 0, results: 0,
+                bloomTested: 0, bloomPassed: 0, bitapMatched: 0,
+            };
+            return [];
+        }
+        // In background / low-power modes we halve the initial batch so the
+        // engine yields more often to the scheduler, leaving more headroom for
+        // whatever the host is doing.
+        const conservative = this._resources?.mode === 'background'
+            || this._resources?.mode === 'low-power';
+        let batch = conservative ? 1024 : 2048;
+        const sched = globalThis.scheduler;
+        const yieldFn = sched && typeof sched.yield === 'function'
+            ? () => sched.yield()
+            : (typeof requestAnimationFrame === 'function'
+                ? () => new Promise(resolve => requestAnimationFrame(() => resolve()))
+                : () => new Promise(resolve => setTimeout(resolve, 0)));
+        for (;;) {
+            const sliceStart = performance.now();
+            const done = w.searchSlice(batch);
+            const sliceMs = performance.now() - sliceStart;
+            if (done === 1)
+                break;
+            // Adapt batch size: if we have headroom in budget, grow; if we're
+            // already over the per-slice target, shrink.
+            if (sliceMs < budgetMs * 0.5 && batch < 32_768)
+                batch *= 2;
+            else if (sliceMs > budgetMs * 1.5 && batch > 512)
+                batch = Math.max(512, Math.floor(batch / 2));
+            await yieldFn();
+        }
+        const ms = performance.now() - t0;
+        const count = w.getResultCount();
+        this._lastSearch = {
+            query: displayQuery,
+            timeMs: ms,
+            results: count,
+            bloomTested: w.getStatBloomTested(),
+            bloomPassed: w.getStatBloomPassed(),
+            bitapMatched: w.getStatBitapMatched(),
+        };
+        return this._collectResults(count, opts, phraseTokens);
+    }
+    /** Materialise results [0..count) into the public SearchResult shape.
+     * When `phraseTokens` is given, each result is kept only if those tokens
+     * appear adjacently in the FULL chunk text — independent of any display
+     * windowing — so phrase queries stay correct under `{ windowed: true }`. */
+    _collectResults(count, opts, phraseTokens) {
+        const w = this._wasm;
+        const windowed = opts.windowed === true;
+        const before = opts.before ?? 60;
+        const after = opts.after ?? 120;
+        const phraseFilter = phraseTokens && phraseTokens.length > 0 ? phraseTokens : null;
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            // Phrase adjacency check against the full chunk text (getSnippet), not
+            // the possibly-cropped display window.
+            if (phraseFilter) {
+                const fl = w.getSnippet(i);
+                const full = fl > 0 ? this._readPad(fl) : '';
+                if (!containsPhrase(full, phraseFilter))
+                    continue;
+            }
+            const score = w.getResultScore(i);
+            const location = w.getResultLocation(i);
+            const matchStart = w.getResultStart(i);
+            const matchEnd = w.getResultEnd(i);
+            const nl = w.getResultDocName(i);
+            const name = nl > 0 ? this._readPad(nl) : '?';
+            const matchCount = w.getResultMatchCount(i);
+            const matches = [];
+            for (let k = 0; k < matchCount; k++) {
+                matches.push({ start: w.getResultMatchStartAt(i, k), end: w.getResultMatchEndAt(i, k) });
+            }
+            if (matches.length === 0)
+                matches.push({ start: matchStart, end: matchEnd });
+            let snippet;
+            let primaryStart = matchStart;
+            let primaryEnd = matchEnd;
+            let adjustedMatches = matches;
+            if (windowed) {
+                const sl = w.getSnippetWindow(i, before, after);
+                snippet = sl > 0 ? this._readPad(sl) : '';
+                const offset = w.getSnippetWindowOffset();
+                const leadingPrefix = offset > 0 ? 4 : 0;
+                const shift = leadingPrefix - offset;
+                adjustedMatches = matches.map(m => ({
+                    start: Math.max(0, m.start + shift),
+                    end: Math.max(0, m.end + shift),
+                }));
+                primaryStart = adjustedMatches[0]?.start ?? 0;
+                primaryEnd = adjustedMatches[0]?.end ?? 0;
+            }
+            else {
+                const sl = w.getSnippet(i);
+                snippet = sl > 0 ? this._readPad(sl) : '';
+            }
+            results.push({
+                documentName: name,
+                location,
+                score,
+                snippet,
+                matchStart: primaryStart,
+                matchEnd: primaryEnd,
+                matches: adjustedMatches,
+            });
         }
         return results;
     }
-    _searchOr(branches, rawQuery) {
+    /** Run all OR branches and merge dedup-by-(doc, location, match). The
+     * branches are already compiled inside the WASM (by prepareQuery); we
+     * iterate them with selectQueryBranch. The "rawQuery" param is kept
+     * only for the lastSearch.query field. */
+    _searchOr(rawQuery, opts) {
+        const w = this._wasm;
         const seen = new Set();
         const all = [];
-        for (const tokens of branches) {
-            const q = tokensToWasmQuery(tokens);
-            if (!q)
-                continue;
-            const results = this._runSearch(q, rawQuery);
+        const n = w.getQueryBranchCount();
+        for (let i = 0; i < n; i++) {
+            w.selectQueryBranch(i);
+            const results = this._runSearch(rawQuery, opts);
             for (const r of results) {
                 const key = `${r.documentName}:${r.location}:${r.matchStart}`;
                 if (!seen.has(key)) {
@@ -398,37 +1918,26 @@ export class AlbexEngine {
                 }
             }
         }
-        // Re-rank the merged list by score descending.
         all.sort((a, b) => b.score - a.score);
         return all;
     }
-    _runSearch(wasmQuery, displayQuery) {
-        const ql = this._writeStr(wasmQuery);
-        this._wasm.setPattern(ql);
+    /** Execute a single search using whichever query branch is currently
+     * active (set via selectQueryBranch). Returns the materialised
+     * SearchResult[]. Caller is responsible for activating a branch first. */
+    _runSearch(displayQuery, opts, phraseTokens) {
+        const w = this._wasm;
         const t0 = performance.now();
-        const count = this._wasm.search();
+        const count = w.search();
         const ms = performance.now() - t0;
         this._lastSearch = {
             query: displayQuery,
             timeMs: ms,
             results: count,
-            bloomTested: this._wasm.getStatBloomTested(),
-            bloomPassed: this._wasm.getStatBloomPassed(),
-            bitapMatched: this._wasm.getStatBitapMatched(),
+            bloomTested: w.getStatBloomTested(),
+            bloomPassed: w.getStatBloomPassed(),
+            bitapMatched: w.getStatBitapMatched(),
         };
-        const results = [];
-        for (let i = 0; i < count; i++) {
-            const score = this._wasm.getResultScore(i);
-            const location = this._wasm.getResultLocation(i);
-            const matchStart = this._wasm.getResultStart(i);
-            const matchEnd = this._wasm.getResultEnd(i);
-            const nl = this._wasm.getResultDocName(i);
-            const name = nl > 0 ? this._readPad(nl) : '?';
-            const sl = this._wasm.getSnippet(i);
-            const snippet = sl > 0 ? this._readPad(sl) : '';
-            results.push({ documentName: name, location, score, snippet, matchStart, matchEnd });
-        }
-        return results;
+        return this._collectResults(count, opts, phraseTokens);
     }
     /** Returns current engine statistics. */
     getStats() {
@@ -438,6 +1947,9 @@ export class AlbexEngine {
             textUsed: this._wasm.getTextUsed(),
             textCapacity: this._wasm.getTextCapacity(),
             wasmMemoryBytes: this._mem.buffer.byteLength,
+            tier: this._tier,
+            maxChunks: this._wasm.getMaxChunks(),
+            maxDocs: this._wasm.getMaxDocs(),
         };
     }
     /** Returns stats from the most recent search, or null. */
@@ -462,18 +1974,276 @@ export class AlbexEngine {
     setMaxResults(max) {
         this._wasm.setMaxResults(Math.max(1, Math.min(200, max)));
     }
+    /**
+     * Enable or disable query stemming.
+     *
+     * - `'off'` (default): tokens are used as-is. Strict matching.
+     * - `'es'`: Spanish stemmer applied to query tokens before search. A query
+     *   for `"contratos"` matches `"contrato"` and vice versa.
+     *
+     * Indexed text is never stemmed, so snippets remain faithful to the
+     * source. Recall improvement comes from queries reducing to shared prefixes.
+     */
+    setLanguage(lang) {
+        this._wasm.setLanguage(lang === 'es' ? 1 : 0);
+    }
     /** Full reset — clears all indexed documents and chunks. */
     reset() {
+        this._assertIdle('reset');
+        this._resetInner();
+    }
+    _resetInner() {
         this._wasm.init();
         this._docs = [];
         this._lastSearch = null;
+        this._diagnostics = [];
+    }
+    /**
+     * Drain and return the diagnostics collected since the last call (or
+     * since the engine was created). Use this to surface recoverable
+     * issues to the caller after `indexFile`, `load`, or any other
+     * operation that may run into a "best-effort" path.
+     *
+     * Example diagnostics:
+     *   - `{kind:'fallback', stage:'pdf', message:'pdf-extract crashed,
+     *      attempting OCR-only fallback', file:'invoice.pdf'}`
+     *   - `{kind:'skipped', stage:'ocr', message:'Tesseract abort on page
+     *      3 image 1; remaining images on this page skipped', file:'...',
+     *      page:3}`
+     *   - `{kind:'fallback', stage:'gpu', message:'GPU pre-filter failed,
+     *      using CPU'}`
+     *
+     * The buffer is cleared on each call; callers should consume the
+     * returned array immediately (e.g. log to their telemetry, surface
+     * a UI banner). After `reset()` the buffer is also cleared.
+     */
+    takeDiagnostics() {
+        const out = this._diagnostics;
+        this._diagnostics = [];
+        return out;
+    }
+    /** Internal: record a diagnostic. Capped at 256 to bound memory. */
+    _diag(entry) {
+        if (this._diagnostics.length >= 256)
+            return;
+        this._diagnostics.push(entry);
+    }
+    /**
+     * Install an OCR adapter. Returns a handle whose `dispose()` removes the
+     * adapter from the engine.
+     *
+     * The contract: the adapter must provide `recognize(image, opts)` that
+     * returns `Promise<OcrAttachedResult>`. The engine validates the
+     * contract at attach time and refuses adapters that don't expose a
+     * recognise function. Only one adapter can be attached at a time; a
+     * second call to `attachOcr` while one is active throws — the caller
+     * must dispose the previous one first.
+     *
+     * @example
+     * ```ts
+     * import { enableOcr } from '@albex/ocr';
+     * const handle = enableOcr(engine);   // internally calls attachOcr
+     * // ... later ...
+     * await handle.dispose();
+     * ```
+     *
+     * Direct use without the companion package:
+     * ```ts
+     * const handle = engine.attachOcr({
+     *   recognize: async (blob) => myCustomOcr(blob),
+     *   options: { alwaysExtractEmbeddedImages: false },
+     * });
+     * ```
+     */
+    attachOcr(adapter) {
+        if (this._ocrAdapter) {
+            throw new AlbexInitError('OCR adapter already attached. Call dispose() on the previous handle before attaching a new one.');
+        }
+        if (typeof adapter?.recognize !== 'function') {
+            throw new AlbexInitError('attachOcr requires an adapter with a recognize(image, opts) function.');
+        }
+        this._ocrAdapter = adapter;
+        return {
+            dispose: async () => {
+                // Idempotent: a double dispose is a no-op rather than a throw.
+                if (this._ocrAdapter === adapter)
+                    this._ocrAdapter = null;
+            },
+        };
+    }
+    // ── Persistence ───────────────────────────────────────────────────────────
+    /**
+     * Persist the current index to OPFS (or IndexedDB as fallback) under `name`.
+     *
+     * The snapshot includes every chunk, document name and text byte currently
+     * indexed. Subsequent `load(name)` calls restore the engine to this exact
+     * state in roughly O(total bytes), bypassing re-parsing.
+     */
+    async save(name) {
+        return this._exclusive(() => this._saveInner(name));
+    }
+    async _saveInner(name) {
+        const w = this._wasm;
+        const total = w.snapshotSize();
+        if (total === 0) {
+            await savePersisted(name, new Uint8Array(0));
+            return;
+        }
+        const out = new Uint8Array(total);
+        let off = 0;
+        while (off < total) {
+            const n = w.snapshotChunk(off, FEED_SIZE);
+            if (n === 0)
+                break;
+            const ptr = w.getBuffer(0);
+            out.set(this._u8(ptr, n), off);
+            off += n;
+        }
+        await savePersisted(name, out);
+        // Reconstruct _docs from the doc table so getStats().documents stays
+        // honest after save (no change here — but symmetric with load()).
+    }
+    /**
+     * Restore an index previously saved with `save(name)`. Returns `true` on
+     * success, `false` if the snapshot is missing or has an incompatible
+     * header (wrong magic, version, or struct sizes).
+     */
+    async load(name) {
+        return this._exclusive(() => this._loadInner(name));
+    }
+    async _loadInner(name) {
+        const bytes = await loadPersisted(name);
+        if (!bytes || bytes.length === 0)
+            return false;
+        const w = this._wasm;
+        // Write the 64-byte header into the scratchpad and validate.
+        if (bytes.length < 64)
+            return false;
+        const ptr = w.getBuffer(64);
+        if (!ptr)
+            return false;
+        this._u8(ptr, 64).set(bytes.subarray(0, 64));
+        if (w.restoreBegin() !== 1)
+            return false;
+        // Stream payload bytes.
+        let off = 64;
+        while (off < bytes.length) {
+            const n = Math.min(FEED_SIZE, bytes.length - off);
+            this._writePad(bytes.subarray(off, off + n));
+            if (w.restoreFeed(n) !== 1)
+                return false;
+            off += n;
+        }
+        // Commit. For v3 this is the atomic apply step (state is untouched
+        // until now); a failure here leaves the previous index intact so the
+        // caller can keep using the engine. For v1/v2 snapshots `restoreCommit`
+        // is a no-op that returns 1 (those formats applied in-place during
+        // restoreFeed and have no rollback to offer). Older binaries that
+        // predate v3 do not export `restoreCommit` — in that case we treat
+        // the load as already committed by feature-detect.
+        if (typeof w.restoreCommit === 'function') {
+            if (w.restoreCommit() !== 1)
+                return false;
+        }
+        // Rebuild _docs metadata from the restored WASM tables.
+        //
+        // What's available after a restore:
+        //   * `name`        — recovered from getDocName(i).
+        //   * `ext`         — derived from the name.
+        //   * `chunks`      — getDocChunkCount(i).
+        //   * `docId`       — getDocId(i).
+        //   * `contentHash` — getDocContentHashPtr(i) when the binary supports
+        //                     snapshot v2 (the export exists) AND the snapshot
+        //                     itself was v2 (the bytes aren't all zero). v1
+        //                     snapshots restore with all-zero hashes → '' here,
+        //                     same as before.
+        //
+        // What's not persisted and therefore zeroed:
+        //   * `indexTimeMs` — no indexing happened in this session.
+        //   * `textBytes`   — engine-wide totals are still available via
+        //                     getStats().textUsed; per-doc breakdown is not
+        //                     stored.
+        const docCount = w.getDocCount();
+        const hasHashExport = typeof w.getDocContentHashPtr === 'function'
+            && typeof w.getDocContentHashLen === 'function';
+        this._docs = [];
+        for (let i = 0; i < docCount; i++) {
+            if (w.isDocDeleted(i))
+                continue;
+            const nameLen = w.getDocName(i);
+            const name = nameLen > 0 ? this._readPad(nameLen) : `restored-${i}`;
+            const dotIdx = name.lastIndexOf('.');
+            const ext = dotIdx > 0 ? name.slice(dotIdx + 1).toLowerCase() : '';
+            let contentHash = '';
+            if (hasHashExport) {
+                const hashLen = w.getDocContentHashLen(); // always 8 today
+                const hashPtr = w.getDocContentHashPtr(i);
+                if (hashPtr !== 0 && hashLen === 8) {
+                    const view = this._u8(hashPtr, 8);
+                    // Copy into a private buffer so subsequent WASM calls cannot
+                    // mutate it under us.
+                    const buf = new Uint8Array(8);
+                    buf.set(view);
+                    contentHash = hashBytesToHex(buf);
+                }
+            }
+            this._docs.push({
+                name,
+                ext,
+                chunks: w.getDocChunkCount(i),
+                indexTimeMs: 0,
+                textBytes: 0,
+                docId: w.getDocId(i),
+                contentHash,
+            });
+        }
+        this._lastSearch = null;
+        return true;
+    }
+    /**
+     * Convenience: load if the snapshot exists, otherwise leave the engine
+     * empty. Returns whether a load actually happened.
+     */
+    async loadOrInit(name) {
+        return this._exclusive(async () => {
+            const loaded = await this._loadInner(name);
+            if (!loaded)
+                this._resetInner();
+            return loaded;
+        });
+    }
+    /** Delete a previously persisted snapshot. */
+    async deleteSnapshot(name) {
+        await deletePersisted(name);
+    }
+    /** List names of persisted snapshots in the current origin. */
+    async listSnapshots() {
+        return listPersisted();
+    }
+    /**
+     * TC39 explicit-resource-management hook (Stage 3 in 2026). Lets the engine
+     * be used with `using` so the references are released deterministically:
+     *
+     *     using engine = new AlbexEngine(opts); await engine.init();
+     *
+     * WebAssembly does not actually expose a way to release linear memory pages
+     * inside a Module instance, so we drop our references to the exports and
+     * the doc list. GC can then reclaim the engine, which in turn releases the
+     * WASM instance and its (typically 20 MB) backing memory.
+     */
+    [Symbol.dispose]() {
+        // Terminal: bypass the idle guard — disposing mid-operation is allowed.
+        this._resetInner();
+        this._unsubscribeResources?.();
+        this._unsubscribeResources = null;
+        this._gpu?.destroy();
+        this._gpu = null;
+        // Null out the references so the engine cannot be reused after disposal
+        // and the WASM instance becomes unreachable.
+        this._wasm = null;
+        this._mem = null;
+        this._pdfWasm = null;
+        this._pdfMem = null;
     }
 }
-AlbexEngine._INDEXERS = {
-    docx: (e, f) => e._indexDocx(f),
-    xlsx: (e, f) => e._indexXlsx(f),
-    pdf: (e, f) => e._indexPdf(f),
-    txt: (e, f) => e._indexTxt(f),
-    xml: (e, f) => e._indexXml(f),
-};
 //# sourceMappingURL=albex.js.map