albex 0.1.0 → 0.6.0

package/src/albex.ts

@@ -14,15 +14,113 @@
  * ```
  */
 
+import {
+  AlbexWasmExports,
+  AlbexPdfExports,
+  asAlbexExports,
+  asAlbexPdfExports,
+} from './wasm-bindings.js';
+import {
+  AlbexError,
+  AlbexInitError,
+  AlbexUnsupportedFormatError,
+  AlbexParseError,
+  AlbexCapacityError,
+  type AlbexCapacityLimit,
+} from './errors.js';
+import {
+  savePersisted,
+  loadPersisted,
+  deletePersisted,
+  listPersisted,
+} from './persistence.js';
+import { detectProfile, shouldUseGpu, type Tier, type DeviceProfile } from './profile.js';
+import { getResourceManager, type ResourceState } 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 type { DeviceProfile, Tier } from './profile.js';
+export { getResourceManager } from './resource-manager.js';
+export type { ResourceState, ResourceMode } from './resource-manager.js';
+export { AlbexPool } from './pool/coordinator.js';
+export type { AlbexPoolOptions } from './pool/coordinator.js';
+export { BloomGpu, packBloomsFromChunks } from './gpu/bloom-runtime.js';
+export { TieredStore } from './tiered-store.js';
+export type { TieredStoreOptions } from './tiered-store.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deprecation warnings — one-shot, fire-and-forget
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _searchStreamWarned = false;
+function warnSearchStreamDeprecated(): void {
+  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.',
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Public types
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface AlbexOptions {
-  /** URL to albex_wasm_bg.wasm (required). */
-  wasmUrl: string;
+  /**
+   * Explicit URL to the main WASM binary.
+   *
+   * If you want automatic tier selection (mini/std/pro chosen from
+   * `deviceMemory`), pass `wasmBaseUrl` instead — the engine will fetch
+   * `albex_wasm_<tier>.wasm` from that directory.
+   */
+  wasmUrl?: string;
+  /**
+   * Base directory containing tiered binaries (`albex_wasm_mini.wasm`,
+   * `_std.wasm`, `_pro.wasm`). Used when `wasmUrl` is omitted.
+   */
+  wasmBaseUrl?: string;
   /** URL to albex_pdf.wasm. Required only if you call indexFile() with PDFs. */
   pdfWasmUrl?: string;
+  /**
+   * Override the tier auto-detection. Pass `'auto'` (default), or an
+   * explicit tier when you know the constraints of your target environment.
+   */
+  /** @deprecated Removed in 0.5.0. Albex no longer has capacity tiers;
+   * pass `'auto'` or omit. Other values are accepted and ignored. */
+  tier?: 'auto' | 'mini' | 'std' | 'pro';
+  /**
+   * SIMD selection. When `'auto'` (default), Albex probes for v128 support
+   * and fetches the `_simd.wasm` variant when available. Pass `'off'` to
+   * stay on the baseline binary even on capable hosts (useful for
+   * regression testing or to align all clients in a corporate deployment).
+   */
+  simd?: 'auto' | 'on' | 'off';
+  /**
+   * GPU acceleration policy for the Bloom pre-filter.
+   *   `'auto'`  — enable when WebGPU is available AND chunk count is large
+   *   `'on'`    — force enable (fall back to CPU silently if GPU fails)
+   *   `'off'`   — never use GPU
+   * Default: `'auto'`.
+   */
+  gpu?: 'auto' | 'on' | 'off';
+  /**
+   * Minimum chunk count before `gpu: 'auto'` engages. Below this threshold
+   * the upload + dispatch overhead is bigger than the speedup. Default: 20_000.
+   */
+  gpuThreshold?: number;
 }
 
 export interface IndexedDocument {
@@ -31,6 +129,17 @@ export interface IndexedDocument {
   chunks: number;
   indexTimeMs: number;
   textBytes: number;
+  /** WASM-side stable identifier (also acts as a slot index after compact). */
+  docId: number;
+  /** 64-bit FNV-1a hex of the source file bytes. Stable across runs. */
+  contentHash: string;
+}
+
+export interface MatchSpan {
+  /** Byte offset within `snippet` where this matched token begins. */
+  start: number;
+  /** Byte offset within `snippet` where this matched token ends (exclusive). */
+  end: number;
 }
 
 export interface SearchResult {
@@ -39,12 +148,38 @@ export interface SearchResult {
   location: number;
   /** Relevance score 0–1000. */
   score: number;
-  /** Raw snippet text (original, with accents). */
+  /** Snippet text. With `windowed` search options this is a substring with
+   *  ASCII ellipsis sentinels (`"... "` / `" ..."`) the UI should render
+   *  as `…`. Without windowing, the full chunk text. */
   snippet: string;
-  /** Match start byte offset within snippet. */
+  /** Primary token match (kept for backwards compatibility). Equal to `matches[0]`. */
   matchStart: number;
-  /** Match end byte offset within snippet (exclusive). */
   matchEnd: number;
+  /** All matched token spans within `snippet`, in query order. Length 1–4. */
+  matches: MatchSpan[];
+}
+
+/**
+ * Options that change how snippets are produced. Both fields are optional.
+ *
+ *   `windowed`     — when true, return a cropped window around the primary
+ *                    match instead of the full chunk text.
+ *   `before/after` — bytes of context to include on each side of the primary
+ *                    match. Defaults: 60 before, 120 after.
+ */
+export interface SearchOptions {
+  windowed?: boolean;
+  before?: number;
+  after?: number;
+  /**
+   * Frame budget in milliseconds for `searchCooperative`. The engine
+   * processes chunks until the budget is exhausted, then yields to the
+   * event loop via `scheduler.yield()` (or `requestAnimationFrame`
+   * fallback) before resuming. Lower = smoother UI; higher = lower latency.
+   *
+   * Default: 8 ms (half a 60 fps frame). Ignored by synchronous `search()`.
+   */
+  frameBudgetMs?: number;
 }
 
 export interface EngineStats {
@@ -53,6 +188,12 @@ export interface EngineStats {
   textUsed: number;
   textCapacity: number;
   wasmMemoryBytes: number;
+  /** Tier loaded at init time (mini/std/pro). */
+  tier: Tier | null;
+  /** Compile-time chunk capacity for the loaded tier. */
+  maxChunks: number;
+  /** Compile-time document capacity for the loaded tier. */
+  maxDocs: number;
 }
 
 export interface SearchStats {
@@ -64,57 +205,57 @@ export interface SearchStats {
   bitapMatched: number;
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Query parsing
-// ─────────────────────────────────────────────────────────────────────────────
-
-type SimpleQuery = { kind: 'simple'; tokens: string[] };
-type PhraseQuery = { kind: 'phrase'; tokens: string[]; raw: string };
-type OrQuery    = { kind: 'or';     branches: string[][] };
-type ParsedQuery = SimpleQuery | PhraseQuery | OrQuery;
-
-function tokenize(q: string): string[] {
-  return q.trim().split(/\s+/).filter(t => t.length > 0);
-}
-
-function parseQuery(q: string): ParsedQuery {
-  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).
+ * One structured warning recorded by the engine during indexFile or
+ * load. Replaces the pre-0.5.0 pattern of scattered `console.warn`
+ * calls. Inspect via `engine.takeDiagnostics()` after the operation.
  */
-function tokensToWasmQuery(tokens: string[]): string {
-  return tokens.slice(0, 4).join(' ');
+export interface AlbexDiagnostic {
+  /** Coarse kind. `'recovered'` means the engine handled the issue and
+   * kept going; `'skipped'` means content was dropped; `'fallback'` means
+   * an alternate code path was used (e.g. lopdf after pdf-extract trap). */
+  kind: 'recovered' | 'skipped' | 'fallback' | 'info';
+  /** Where in the pipeline this happened. Free-form short tag. */
+  stage: 'pdf' | 'ocr' | 'gpu' | 'persistence' | 'network';
+  /** Human-readable message safe to surface in a UI. */
+  message: string;
+  /** Optional file the issue belongs to. */
+  file?: string;
+  /** Optional page number (1-based for PDFs). */
+  page?: number;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// 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: string, tokens: string[], maxGap = 30): boolean {
   const norm = (s: string): string =>
@@ -147,7 +288,7 @@ function zipCentralDir(bytes: Uint8Array): { v: DataView; cdOff: number; cdN: nu
   const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   let p = bytes.length - 22;
   while (p >= 0 && v.getUint32(p, true) !== 0x06054b50) p--;
-  if (p < 0) throw new Error('Not a ZIP file');
+  if (p < 0) 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) };
 }
 
@@ -176,7 +317,7 @@ async function findZipEntry(bytes: Uint8Array, name: string): Promise<Uint8Array
     }
     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: Uint8Array, v: DataView, off: number, compSize: number): Promise<Uint8Array> {
@@ -202,7 +343,7 @@ async function decompEntry(bytes: Uint8Array, v: DataView, off: number, compSize
     for (const c of chunks) { out.set(c, o); o += c.length; }
     return out;
   }
-  throw new Error(`Unsupported ZIP compression method ${meth}`);
+  throw new AlbexParseError('zip', `Unsupported ZIP compression method ${meth}`);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -211,64 +352,577 @@ async function decompEntry(bytes: Uint8Array, v: DataView, off: number, compSize
 
 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: string): bigint {
+  // 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: string): Uint8Array {
+  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: Record<number, string> = {
+  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: number): string {
+  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: string,
+  body: string,
+  header: (block: string, name: string) => string,
+): string {
+  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: string): string {
+  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: string): string {
+  // First pass: collect the raw bytes so we can decode multi-byte UTF-8.
+  const bytes: number[] = [];
+  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: Uint8Array): string {
+  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: () => WebAssembly.Memory): WebAssembly.Imports {
+/**
+ * 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: WebAssembly.Module,
+  getPdfMem: () => WebAssembly.Memory | null,
+): WebAssembly.Imports {
   const heap: unknown[] = [];
   let freeIdx = -1;
-  return {
-    __wbindgen_placeholder__: {
-      __wbindgen_describe: () => {},
-      __wbg_getRandomValues_3f44b700395062e5: (ptr: number, len: number) => {
-        const mem = getPdfMem();
-        crypto.getRandomValues(new Uint8Array(mem.buffer, ptr >>> 0, len >>> 0));
-      },
-      __wbindgen_object_drop_ref: (idx: number) => {
-        heap[idx] = freeIdx; freeIdx = idx;
-      },
-    },
-    __wbindgen_externref_xform__: {
-      __wbindgen_externref_table_grow: (delta: number) => {
-        const old = heap.length;
-        for (let i = 0; i < delta; i++) heap.push(undefined);
-        return old;
-      },
-      __wbindgen_externref_table_set_null: (idx: number) => { heap[idx] = undefined; },
-    },
+  const required = WebAssembly.Module.imports(module);
+
+  const fillRandom = (ptr: number, len: number): void => {
+    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: string, name: string): unknown => {
+    // 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: number) => { heap[idx] = freeIdx; freeIdx = idx; };
+      case '__wbindgen_externref_table_grow':
+        return (delta: number) => {
+          const old = heap.length;
+          for (let i = 0; i < delta; i++) heap.push(undefined);
+          return old;
+        };
+      case '__wbindgen_externref_table_set_null':
+        return (idx: number) => { 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: Record<string, Record<string, unknown>> = {};
+  for (const { module: modName, name } of required) {
+    if (!imports[modName]) imports[modName] = {};
+    imports[modName]![name] = resolveByName(modName, name);
+  }
+  return imports as WebAssembly.Imports;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // AlbexEngine
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Result shape returned by an attached OCR module. Kept structural here so
+ * the main package has no runtime dependency on `@albex/ocr` — the optional
+ * shape is just a contract.
+ */
+export interface OcrAttachedResult {
+  text: string;
+  confidence: number;
+  timeMs: number;
+}
+
+export interface OcrAttachedOptions {
+  lang?: string;
+  hint?: string;
+}
+
+/**
+ * Contract the engine accepts from an OCR plugin. `@albex/ocr` is the
+ * canonical implementation, but any module that satisfies this interface
+ * can be attached via `engine.attachOcr(adapter)`.
+ */
+export interface OcrAdapter {
+  /** Invoked by the engine to OCR a single image. Receives whatever the
+   * caller passes (Blob, ArrayBuffer, etc.); the adapter is responsible
+   * for accepting that input. Must return text + confidence. */
+  recognize(image: unknown, opts?: OcrAttachedOptions): Promise<OcrAttachedResult>;
+
+  /** Engine-side switches the adapter wants honoured. The only one
+   * defined today is `alwaysExtractEmbeddedImages`, which turns on the
+   * hybrid PDF OCR pass. New flags can be added without breaking the
+   * adapter interface. */
+  options?: {
+    /** When true, every PDF (native or scanned) is walked for embedded
+     * images and each qualifying image is sent to `recognize`. Off by
+     * default to keep performance predictable on native PDFs. */
+    alwaysExtractEmbeddedImages?: boolean;
+  };
+}
+
+/** Returned by `attachOcr`. Holds the lifecycle handles for the plugin.
+ * Calling `dispose()` removes the adapter from the engine; subsequent
+ * `engine.ocrImage` access returns `undefined` again. */
+export interface OcrHandle {
+  /** Detach the plugin and tear down any resources it holds. After this,
+   * the engine reverts to "no OCR" — scanned PDFs go back to registering
+   * with zero chunks. */
+  dispose(): Promise<void>;
+}
+
 export class AlbexEngine {
   // ── main WASM ──
-  private _wasm!: WebAssembly.Exports;
+  private _wasm!: AlbexWasmExports;
   private _mem!: WebAssembly.Memory;
 
+  /**
+   * 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(): ((image: unknown, opts?: OcrAttachedOptions) => Promise<OcrAttachedResult>) | undefined {
+    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. */
+  private _ocrAdapter: OcrAdapter | null = null;
+
   // ── PDF WASM (lazy) ──
-  private _pdfWasm: WebAssembly.Exports | null = null;
+  private _pdfWasm: AlbexPdfExports | null = null;
   private _pdfMem: WebAssembly.Memory | null = null;
 
   private _docs: IndexedDocument[] = [];
   private _lastSearch: SearchStats | null = 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). */
+  private _diagnostics: AlbexDiagnostic[] = [];
+  private _tier: Tier | null = null;
+  private _simd: boolean = false;
+  private _profile: DeviceProfile | null = null;
+  private _resources: ResourceState | null = null;
+  private _gpu: BloomGpu | null = null;
+  private _gpuChunkCountUploaded = 0;
+  private _unsubscribeResources: (() => void) | null = null;
   private readonly _opts: AlbexOptions;
 
+  // ── 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).
+  private _opChain: Promise<unknown> = Promise.resolve();
+  private _busy = false;
+
   constructor(opts: AlbexOptions) {
     this._opts = opts;
   }
 
+  /** Serialize an async engine operation behind any in-flight one. */
+  private _exclusive<T>(fn: () => Promise<T>): Promise<T> {
+    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 as Promise<T>;
+  }
+
+  /** Guard a synchronous mutator/search: refuse to run mid-async-operation
+   * rather than silently corrupt the shared WASM state. */
+  private _assertIdle(method: string): void {
+    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. */
+  private _autoCompactIfNeeded(): void {
+    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(): Promise<void> {
-    const res = await fetch(this._opts.wasmUrl);
-    if (!res.ok) throw new Error(`Failed to fetch WASM: ${res.status}`);
+    const url = await this._resolveWasmUrl();
+    const res = await fetch(url);
+    if (!res.ok) 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 as WebAssembly.Memory;
-    (this._wasm.init as Function)();
+    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`.
+   */
+  private async _resolveWasmUrl(): Promise<string> {
+    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(): Tier | null { return this._tier; }
+
+  /** True if the SIMD-accelerated binary was loaded. */
+  get simdEnabled(): boolean { return this._simd; }
+
+  /** True if a WebGPU device is acquired and the next search will use it. */
+  get gpuEngaged(): boolean { 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`.
+   */
+  private _shouldEngageGpu(): boolean {
+    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.
+   */
+  private async _gpuPreFilter(wasmQuery: string): Promise<void> {
+    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 ──────────────────────────────────────────────────────
@@ -278,8 +932,8 @@ export class AlbexEngine {
   }
 
   private _writePad(b: Uint8Array): number {
-    const ptr = (this._wasm.getBuffer as Function)(b.length) as number;
-    if (!ptr) throw new Error('Scratchpad too small for this chunk');
+    const ptr = this._wasm.getBuffer(b.length);
+    if (!ptr) throw new AlbexCapacityError(`Scratchpad too small for ${b.length} bytes`);
     this._u8(ptr, b.length).set(b);
     return ptr;
   }
@@ -291,7 +945,7 @@ export class AlbexEngine {
   }
 
   private _readPad(n: number): string {
-    const ptr = (this._wasm.getBuffer as Function)(0) as number;
+    const ptr = this._wasm.getBuffer(0);
     return _dec.decode(this._u8(ptr, n));
   }
 
@@ -300,15 +954,45 @@ export class AlbexEngine {
     for (let i = 0; i < b.length; i += FEED_SIZE) {
       const c = b.subarray(i, i + FEED_SIZE);
       this._writePad(c);
-      (this._wasm.feedText as Function)(c.length);
+      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.
+   */
+  private _contentHash(bytes: Uint8Array): string {
+    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;
+  }
+
   private _feedXmlBytes(xml: Uint8Array, fn: 'feedXmlBytes' | 'feedXlsxBytes'): void {
+    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] as Function)(c.length);
+      feeder(c.length);
     }
   }
 
@@ -316,30 +1000,45 @@ export class AlbexEngine {
 
   private async _ensurePdfWasm(): Promise<void> {
     if (this._pdfWasm) return;
-    if (!this._opts.pdfWasmUrl) throw new Error('pdfWasmUrl not set in AlbexOptions');
-    const res = await fetch(this._opts.pdfWasmUrl);
-    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 as WebAssembly.Memory;
+    // 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 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 ──────────────────────────────────────────────────────────────
 
-  private async _indexDocx(file: File): Promise<number> {
-    const bytes = new Uint8Array(await file.arrayBuffer());
-    const xml   = await findZipEntry(bytes, 'word/document.xml');
-    (this._wasm.setDocumentName as Function)(this._writeStr(file.name));
-    (this._wasm.beginDocument as Function)();
+  private async _indexDocx(file: File, bytes: Uint8Array): Promise<number> {
+    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 as Function)() as number;
+    return this._wasm.endDocument();
   }
 
-  private async _indexXlsx(file: File): Promise<number> {
-    const bytes = new Uint8Array(await file.arrayBuffer());
-    (this._wasm.setDocumentName as Function)(this._writeStr(file.name));
-    (this._wasm.beginXlsx as Function)();
+  private async _indexXlsx(file: File, bytes: Uint8Array): Promise<number> {
+    this._wasm.setDocumentName(this._writeStr(file.name));
+    this._wasm.beginXlsx();
 
     try {
       const xml = await findZipEntry(bytes, 'xl/sharedStrings.xml');
@@ -354,80 +1053,699 @@ export class AlbexEngine {
       } catch { /* skip corrupt/missing sheet */ }
     }
 
-    return (this._wasm.endDocument as Function)() as number;
+    return this._wasm.endDocument();
   }
 
-  private async _indexPdf(file: File): Promise<number> {
+  private async _indexPdf(file: File, bytes: Uint8Array): Promise<number> {
     await this._ensurePdfWasm();
-    const pw   = this._pdfWasm!;
-    const pm   = this._pdfMem!;
-    const bytes = new Uint8Array(await file.arrayBuffer());
-
-    const inPtr    = (pw.allocInput as Function)(bytes.length) as number;
+    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 as Function)(bytes.length) as number;
 
-    (this._wasm.setDocumentName as Function)(this._writeStr(file.name));
-    (this._wasm.beginDocument as Function)();
+    // 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: number;
+    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.
-      return (this._wasm.endDocument as Function)() as number;
+      // 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 as Function)() as number;
-      const errPtr = (pw.getErrorPtr as Function)() as number;
+      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 as Function)(p) as number;
+      const len = pw.getPageLen(p);
       if (!len) continue;
-      const text = new TextDecoder('utf-8').decode(
-        new Uint8Array(pm.buffer, (pw.getPagePtr as Function)(p) as number, 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 as Function)();
+      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 as Function)() as number;
+    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.
+   */
+  private async _indexPdfScanned(pw: AlbexPdfExports): Promise<void> {
+    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();
+      }
+    }
   }
 
-  private async _indexTxt(file: File): Promise<number> {
-    const text = await file.text();
-    (this._wasm.setDocumentName as Function)(this._writeStr(file.name));
-    (this._wasm.beginDocument as Function)();
+  /**
+   * 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.
+   */
+  private async _ocrPageEmbeddedImages(
+    pw: AlbexPdfExports,
+    page: number,
+  ): Promise<string | null> {
+    const ocr = this.ocrImage;
+    if (!ocr) return '';
+
+    let imageCount: number;
+    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 as ArrayBuffer], { 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.
+   */
+  private async _indexPdfViaImagesOnly(
+    file: File,
+    bytes: Uint8Array,
+    originalError: string,
+  ): Promise<number | null> {
+    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: number;
+    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();
+  }
+
+  private async _indexTxt(file: File, bytes: Uint8Array): Promise<number> {
+    const text = _dec.decode(bytes);
+    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 as Function)(); }
+      if (l) { this._feedText(l); this._wasm.flushParagraph(); }
     }
-    return (this._wasm.endDocument as Function)() as number;
+    return this._wasm.endDocument();
   }
 
-  private async _indexXml(file: File): Promise<number> {
-    const plain = (await file.text())
+  private async _indexXml(file: File, bytes: Uint8Array): Promise<number> {
+    const plain = _dec.decode(bytes)
       .replace(/<[^]*?>/g, '\n')
       .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
       .replace(/&quot;/g, '"').replace(/&apos;/g, "'")
       .replace(/[ \t]+/g, ' ').trim();
-    (this._wasm.setDocumentName as Function)(this._writeStr(file.name));
-    (this._wasm.beginDocument as Function)();
+    this._wasm.setDocumentName(this._writeStr(file.name));
+    this._wasm.beginDocument();
     for (const seg of plain.split(/\n{2,}/)) {
       const l = seg.replace(/\n/g, ' ').trim();
-      if (l) { this._feedText(l); (this._wasm.flushParagraph as Function)(); }
+      if (l) { this._feedText(l); this._wasm.flushParagraph(); }
+    }
+    return this._wasm.endDocument();
+  }
+
+  // ── Markdown ─────────────────────────────────────────────────────────────
+  // Strip CommonMark inline marks but keep word content. Paragraphs split on
+  // blank lines, same convention as TXT/XML.
+  private async _indexMd(file: File, bytes: Uint8Array): Promise<number> {
+    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.
+  private async _indexHtml(file: File, bytes: Uint8Array): Promise<number> {
+    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).
+  private async _indexJson(file: File, bytes: Uint8Array): Promise<number> {
+    let root: unknown;
+    try { root = JSON.parse(_dec.decode(bytes)); }
+    catch (e) { throw new AlbexParseError('json', (e as Error).message); }
+
+    this._wasm.setDocumentName(this._writeStr(file.name));
+    this._wasm.beginDocument();
+
+    const visit = (v: unknown): void => {
+      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 as Record<string, unknown>)) {
+          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).
+  private async _indexCsv(file: File, bytes: Uint8Array): Promise<number> {
+    // 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: string[] = [];
+    let field = '';
+    let inQuoted = false;
+    const flushRow = (): void => {
+      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.
+  private async _indexEml(file: File, bytes: Uint8Array): Promise<number> {
+    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: string, name: string): string => {
+      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.
+   */
+  private _extractEmlTextPlain(
+    headersBlock: string,
+    body: string,
+    header: (block: string, name: string) => string,
+  ): string | null {
+    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;
     }
-    return (this._wasm.endDocument as Function)() as number;
+
+    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).
+  private async _indexRtf(file: File, bytes: Uint8Array): Promise<number> {
+    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();
   }
 
-  private static readonly _INDEXERS: Record<string, (engine: AlbexEngine, file: File) => Promise<number>> = {
-    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),
+  private static readonly _INDEXERS: Record<string, (engine: AlbexEngine, file: File, bytes: Uint8Array) => Promise<number>> = {
+    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 ────────────────────────────────────────────────────────────
@@ -437,106 +1755,457 @@ export class AlbexEngine {
    * Throws for unsupported formats or parse errors.
    */
   async indexFile(file: File): Promise<IndexedDocument> {
+    return this._exclusive(() => this._indexFileInner(file));
+  }
+
+  private async _indexFileInner(file: File): Promise<IndexedDocument> {
     const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
     const indexer = AlbexEngine._INDEXERS[ext];
-    if (!indexer) throw new Error(`Unsupported format: .${ext}`);
+    if (!indexer) 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 = 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: AlbexCapacityLimit =
+        (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 t0     = performance.now();
-    const textPre = (this._wasm.getTextUsed as Function)() as number;
-    const chunks  = await indexer(this, file);
     const doc: IndexedDocument = {
       name:        file.name,
       ext,
       chunks,
       indexTimeMs: performance.now() - t0,
-      textBytes:   ((this._wasm.getTextUsed as Function)() as number) - 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: string): boolean {
+    this._assertIdle('removeDocument');
+    return this._removeDocumentInner(id);
+  }
+
+  private _removeDocumentInner(id: string): boolean {
+    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: string, newFile: File): Promise<IndexedDocument> {
+    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(): void {
+    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: string, opts: SearchOptions = {}): SearchResult[] {
+    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. */
+  private _branchTokens(i: number): string[] {
+    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: string, opts: SearchOptions = {}): AsyncIterable<SearchResult> {
+    // 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. */
+  private async _searchCooperativeCollect(query: string, opts: SearchOptions): Promise<SearchResult[]> {
+    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<string>();
+      const all: SearchResult[] = [];
+      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: string): SearchResult[] {
-    const parsed = parseQuery(query);
+  async *searchStream(query: string, opts: SearchOptions = {}): AsyncIterable<SearchResult> {
+    warnSearchStreamDeprecated();
+    yield* this.searchCooperative(query, opts);
+  }
 
-    if (parsed.kind === 'or') {
-      return this._searchOr(parsed.branches, query);
+  /**
+   * 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.
+   */
+  private async _runSearchBudgeted(
+    displayQuery: string,
+    opts: SearchOptions,
+    budgetMs: number,
+    phraseTokens?: string[],
+    branchIdx = 0,
+  ): Promise<SearchResult[]> {
+    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);
+    const t0 = performance.now();
+    if (w.searchBegin() === 0) {
+      this._lastSearch = {
+        query: displayQuery, timeMs: 0, results: 0,
+        bloomTested: 0, bloomPassed: 0, bitapMatched: 0,
+      };
+      return [];
+    }
 
-    if (parsed.kind === 'phrase') {
-      return results.filter(r => containsPhrase(r.snippet, parsed.tokens));
+    // 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;
+    // `scheduler.yield()` is the cleanest way to defer to the event loop in
+    // 2026 (Chrome 129+). Fall back to `requestAnimationFrame` on older
+    // browsers and Node test environments.
+    type Sched = { yield: () => Promise<void> };
+    const sched = (globalThis as unknown as { scheduler?: Sched }).scheduler;
+    const yieldFn: () => Promise<void> = sched && typeof sched.yield === 'function'
+      ? () => sched.yield()
+      : (typeof requestAnimationFrame === 'function'
+        ? () => new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+        : () => new Promise<void>(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 }`. */
+  private _collectResults(count: number, opts: SearchOptions, phraseTokens?: string[]): SearchResult[] {
+    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: SearchResult[] = [];
+    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: MatchSpan[] = [];
+      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: string;
+      let primaryStart = matchStart;
+      let primaryEnd   = matchEnd;
+      let adjustedMatches: MatchSpan[] = 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;
   }
 
-  private _searchOr(branches: string[][], rawQuery: string): SearchResult[] {
+  /** 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. */
+  private _searchOr(rawQuery: string, opts: SearchOptions): SearchResult[] {
+    const w = this._wasm;
     const seen = new Set<string>();
     const all: SearchResult[] = [];
-
-    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)) { seen.add(key); all.push(r); }
       }
     }
-
-    // Re-rank the merged list by score descending.
     all.sort((a, b) => b.score - a.score);
     return all;
   }
 
-  private _runSearch(wasmQuery: string, displayQuery: string): SearchResult[] {
-    const ql  = this._writeStr(wasmQuery);
-    (this._wasm.setPattern as Function)(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. */
+  private _runSearch(displayQuery: string, opts: SearchOptions, phraseTokens?: string[]): SearchResult[] {
+    const w  = this._wasm;
 
     const t0    = performance.now();
-    const count = (this._wasm.search as Function)() as number;
+    const count = w.search();
     const ms    = performance.now() - t0;
 
     this._lastSearch = {
       query:        displayQuery,
       timeMs:       ms,
       results:      count,
-      bloomTested:  (this._wasm.getStatBloomTested as Function)() as number,
-      bloomPassed:  (this._wasm.getStatBloomPassed as Function)() as number,
-      bitapMatched: (this._wasm.getStatBitapMatched as Function)() as number,
+      bloomTested:  w.getStatBloomTested(),
+      bloomPassed:  w.getStatBloomPassed(),
+      bitapMatched: w.getStatBitapMatched(),
     };
 
-    const results: SearchResult[] = [];
-    for (let i = 0; i < count; i++) {
-      const score    = (this._wasm.getResultScore    as Function)(i) as number;
-      const location = (this._wasm.getResultLocation as Function)(i) as number;
-      const matchStart = (this._wasm.getResultStart  as Function)(i) as number;
-      const matchEnd   = (this._wasm.getResultEnd    as Function)(i) as number;
-      const nl         = (this._wasm.getResultDocName as Function)(i) as number;
-      const name       = nl > 0 ? this._readPad(nl) : '?';
-      const sl         = (this._wasm.getSnippet      as Function)(i) as number;
-      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(): EngineStats {
     return {
-      documents:      this._docs.length,
-      chunks:         (this._wasm.getChunkCount    as Function)() as number,
-      textUsed:       (this._wasm.getTextUsed      as Function)() as number,
-      textCapacity:   (this._wasm.getTextCapacity  as Function)() as number,
+      documents:       this._docs.length,
+      chunks:          this._wasm.getChunkCount(),
+      textUsed:        this._wasm.getTextUsed(),
+      textCapacity:    this._wasm.getTextCapacity(),
       wasmMemoryBytes: this._mem.buffer.byteLength,
+      tier:            this._tier,
+      maxChunks:       this._wasm.getMaxChunks(),
+      maxDocs:         this._wasm.getMaxDocs(),
     };
   }
 
@@ -557,21 +2226,299 @@ export class AlbexEngine {
 
   /** Configure search sensitivity. */
   setMaxErrors(errors: 0 | 1 | 2 | 3): void {
-    (this._wasm.setMaxErrors as Function)(errors);
+    this._wasm.setMaxErrors(errors);
   }
 
   setThreshold(threshold: number): void {
-    (this._wasm.setThreshold as Function)(Math.max(0, Math.min(1000, threshold)));
+    this._wasm.setThreshold(Math.max(0, Math.min(1000, threshold)));
   }
 
   setMaxResults(max: number): void {
-    (this._wasm.setMaxResults as Function)(Math.max(1, Math.min(200, 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: 'off' | 'es'): void {
+    this._wasm.setLanguage(lang === 'es' ? 1 : 0);
   }
 
   /** Full reset — clears all indexed documents and chunks. */
   reset(): void {
-    (this._wasm.init as Function)();
+    this._assertIdle('reset');
+    this._resetInner();
+  }
+
+  private _resetInner(): void {
+    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(): AlbexDiagnostic[] {
+    const out = this._diagnostics;
+    this._diagnostics = [];
+    return out;
+  }
+
+  /** Internal: record a diagnostic. Capped at 256 to bound memory. */
+  private _diag(entry: AlbexDiagnostic): void {
+    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: OcrAdapter): OcrHandle {
+    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: string): Promise<void> {
+    return this._exclusive(() => this._saveInner(name));
+  }
+
+  private async _saveInner(name: string): Promise<void> {
+    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: string): Promise<boolean> {
+    return this._exclusive(() => this._loadInner(name));
+  }
+
+  private async _loadInner(name: string): Promise<boolean> {
+    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: string): Promise<boolean> {
+    return this._exclusive(async () => {
+      const loaded = await this._loadInner(name);
+      if (!loaded) this._resetInner();
+      return loaded;
+    });
+  }
+
+  /** Delete a previously persisted snapshot. */
+  async deleteSnapshot(name: string): Promise<void> {
+    await deletePersisted(name);
+  }
+
+  /** List names of persisted snapshots in the current origin. */
+  async listSnapshots(): Promise<string[]> {
+    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](): void {
+    // 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 as unknown as AlbexWasmExports;
+    this._mem     = null as unknown as WebAssembly.Memory;
+    this._pdfWasm = null;
+    this._pdfMem  = null;
   }
 }