albex 0.1.0 → 0.3.0

package/src/albex.ts

@@ -14,15 +14,109 @@
  * ```
  */
 
+import {
+  AlbexWasmExports,
+  AlbexPdfExports,
+  asAlbexExports,
+  asAlbexPdfExports,
+} from './wasm-bindings.js';
+import {
+  AlbexInitError,
+  AlbexUnsupportedFormatError,
+  AlbexParseError,
+  AlbexCapacityError,
+} from './errors.js';
+import {
+  savePersisted,
+  loadPersisted,
+  deletePersisted,
+  listPersisted,
+} from './persistence.js';
+import { detectProfile, pickTier, 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.
+   */
+  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 +125,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 +144,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 +184,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 {
@@ -147,7 +284,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 +313,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 +339,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,50 +348,347 @@ 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;
+}
+
+function contentHash(bytes: Uint8Array): string {
+  // 64-bit arithmetic via two 32-bit halves (no BigInt to keep it fast in
+  // engines without optimised BigInt support).
+  let hi = 0xcbf29ce4 | 0;
+  let lo = 0x84222325 | 0;
+  // FNV prime: 0x100000001b3 = (0x100 << 32) | 0x000001b3
+  for (let i = 0; i < bytes.length; i++) {
+    lo ^= bytes[i]!;
+    // multiply by FNV prime
+    // (hi:lo) *= 0x100000001b3
+    // low * prime
+    const lo_lo = (lo & 0xffff) * 0x1b3;
+    const lo_hi = (lo >>> 16) * 0x1b3;
+    let new_lo  = (lo_lo + ((lo_hi & 0xffff) << 16)) | 0;
+    let carry   = (lo_hi >>> 16) + ((lo_lo + ((lo_hi & 0xffff) << 16)) > 0xffffffff ? 1 : 0);
+    // hi*prime + carry
+    const hi_lo = (hi & 0xffff) * 0x1b3;
+    const hi_hi = (hi >>> 16) * 0x1b3;
+    const new_hi = ((hi_lo + ((hi_hi & 0xffff) << 16)) | 0) + carry + lo; // + lo because high 33rd bit
+    lo = new_lo;
+    hi = new_hi | 0;
+  }
+  const hexHi = (hi >>> 0).toString(16).padStart(8, '0');
+  const hexLo = (lo >>> 0).toString(16).padStart(8, '0');
+  return hexHi + hexLo;
+}
+
+/**
+ * 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 — return a stub that warns when called. Loading still
+    // succeeds; only an actually-invoked unknown import will surface.
+    return (...args: unknown[]) => {
+      console.warn(`[albex] unhandled PDF WASM import ${modName}.${name}`, args);
+    };
+  };
+
+  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;
+}
+
 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.
+   */
+  ocrImage?: (image: unknown, opts?: OcrAttachedOptions) => Promise<OcrAttachedResult>;
+
+  /**
+   * Optional OCR-side configuration set by `@albex/ocr::enableOcr`. Read
+   * by the engine to decide whether to invoke OCR on top of the text it
+   * already extracted from a PDF (hybrid PDFs: native text + images that
+   * also contain text, like stamps, scanned annexes, or diagrams with
+   * labels).
+   *
+   * When `alwaysExtractEmbeddedImages` is true, every page of every PDF
+   * passes through `extractPageImages` after the normal text extraction;
+   * any image that meets the size filter (200×200 in Rust) is fed to
+   * `ocrImage`. Performance cost: 1–3 s per qualifying image.
+   *
+   * Off by default — set this opt-in via the OCR module's options.
+   */
+  ocrConfig?: { alwaysExtractEmbeddedImages?: boolean };
+
   // ── 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;
+  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;
 
   constructor(opts: AlbexOptions) {
@@ -263,12 +697,161 @@ export class AlbexEngine {
 
   /** 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.
+    if (!o.wasmBaseUrl) {
+      // We can't tier-select with one URL, so fall back to std baseline.
+      // The integrator who wants tier optimisation must opt in via wasmBaseUrl.
+      this._tier = 'std';
+      this._simd = false;
+      return new URL('../wasm/pkg/albex_wasm_bg.wasm', import.meta.url).href;
+    }
+
+    let tier: Tier;
+    if (o.tier && o.tier !== 'auto') tier = o.tier;
+    else                             tier = pickTier(profile);
+    this._tier = tier;
+
+    const simd = o.simd === 'on'
+      ? true
+      : o.simd === 'off'
+        ? false
+        : !!profile?.wasm.simd;
+    this._simd = simd;
+
+    const suffix = simd ? `${tier}_simd` : tier;
+    const base = o.wasmBaseUrl.replace(/\/+$/, '');
+    return `${base}/albex_wasm_${suffix}.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 +861,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 +874,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 +883,16 @@ 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);
     }
   }
 
   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 +900,42 @@ 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) {
+      console.info('[albex] 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 +950,704 @@ 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 module is wired with
+    // `alwaysExtractEmbeddedImages: true`, also walk every page for
+    // embedded images and OCR them on top of the vector text.
+    //
+    // We always log the decision so users debugging "why isn't OCR
+    // firing on my hybrid PDF" can see which precondition failed.
+    const hybridOn = !!this.ocrConfig?.alwaysExtractEmbeddedImages;
+    const hasOcr   = !!this.ocrImage;
+    const binSupportsImages = typeof pw.extractPageImages === 'function'
+                            && typeof pw.getPageCount === 'function';
+    console.log(`[albex] hybrid OCR decision: ocrImage=${hasOcr} ocrConfig.alwaysExtractEmbeddedImages=${hybridOn} binarySupportsImages=${binSupportsImages}`);
+
+    if (hasOcr && hybridOn && binSupportsImages) {
+      const totalPages = pw.getPageCount();
+      console.log(`[albex] hybrid OCR pass starting over ${totalPages} page(s)`);
+      for (let p = 0; p < totalPages; p++) {
+        const ocrText = await this._ocrPageEmbeddedImages(pw, p);
+        if (ocrText === null) break; // WASM trapped, stop hybrid pass.
+        if (ocrText) {
+          this._feedText(ocrText);
+          this._wasm.flushParagraph();
+        }
+      }
+    }
+
+    return this._wasm.endDocument();
+  }
+
+  /**
+   * Scanned-PDF OCR fallback. Called from `_indexPdf` when `extractPdf`
+   * returns `-2` (image-only PDF) AND `@albex/ocr` has been wired via
+   * `enableOcr(engine)`.
+   *
+   * Walks every page of the PDF, extracts embedded JPEG / JPEG2000 image
+   * XObjects, runs each through `engine.ocrImage`, and feeds the recognised
+   * text into the index — one paragraph per page so search snippets stay
+   * tied to the page they came from.
+   *
+   * Failure modes handled here (none re-thrown — the goal is best-effort
+   * indexing, not all-or-nothing):
+   *
+   *   * A page's `extractPageImages` traps the WASM instance: the instance
+   *     is discarded so the next PDF starts fresh, and we stop iterating
+   *     (no more pages can be read from a poisoned instance). The doc is
+   *     still committed with whatever text we got from earlier pages.
+   *   * An individual image fails to OCR (Tesseract decode error, JP2 not
+   *     supported in this browser, etc.): we skip that image and keep
+   *     going. Partial coverage beats nothing.
+   *   * A page yields no extractable images (e.g. uses Flate/CCITT/JBIG2):
+   *     no paragraph is emitted; the page contributes 0 chunks.
+   */
+  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();
+      }
+    }
+  }
+
+  /**
+   * 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;
+      console.warn(`[albex] PDF image extractor trapped on page ${page + 1}: ${e instanceof Error ? e.message : String(e)}. Stopping OCR.`);
+      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 });
+
+      // Defensive diagnostics: when an OCR call goes wrong (Tesseract
+      // worker abort, malformed JPEG, etc.) the first thing we want to
+      // see is whether we even handed it valid image bytes. A real JPEG
+      // starts with FF D8 FF (E0 for JFIF, E1 for EXIF). A JPEG2000
+      // starts with 00 00 00 0C 6A 50 20 20.
+      const magic = Array.from(copy.subarray(0, 4))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join(' ');
+      console.log(`[albex] OCR page ${page + 1} image ${i + 1}/${imageCount}: kind=${kind} (${mime}) len=${len} bytes magic=${magic}`);
+
+      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.
+        console.warn(`[albex] OCR failed on page ${page + 1} image ${i + 1}: ${e instanceof Error ? e.message : String(e)}`);
+      }
     }
 
-    return (this._wasm.endDocument as Function)() as number;
+    return pageText;
   }
 
-  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)();
+  /**
+   * 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) {
+      console.warn(`[albex] 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();
+    console.info(`[albex] pdf-extract failed (${originalError}); attempting OCR-only fallback via lopdf for ${file.name}`);
+    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 as Function)() as number;
+    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),
+  /**
+   * 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;
+    }
+
+    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, 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 ────────────────────────────────────────────────────────────
@@ -439,36 +1659,111 @@ export class AlbexEngine {
   async indexFile(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  = 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);
+    // 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 {
+    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> {
+    this.removeDocument(name);
+    // Force a unique-hash path by indexing directly; if the new file happens
+    // to hash identically to a still-tracked document, the dedupe in
+    // indexFile will return that one. The remove above prevents the
+    // common case.
+    return this.indexFile(newFile);
+  }
+
+  /**
+   * 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._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): SearchResult[] {
+  search(query: string, opts: SearchOptions = {}): SearchResult[] {
     const parsed = parseQuery(query);
 
     if (parsed.kind === 'or') {
-      return this._searchOr(parsed.branches, query);
+      return this._searchOr(parsed.branches, query, opts);
     }
 
-    const results = this._runSearch(tokensToWasmQuery(parsed.tokens), query);
+    const results = this._runSearch(tokensToWasmQuery(parsed.tokens), query, opts);
 
     if (parsed.kind === 'phrase') {
       return results.filter(r => containsPhrase(r.snippet, parsed.tokens));
@@ -477,14 +1772,215 @@ export class AlbexEngine {
     return results;
   }
 
-  private _searchOr(branches: string[][], rawQuery: string): SearchResult[] {
+  /**
+   * 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> {
+    const parsed = parseQuery(query);
+    const budget = opts.frameBudgetMs ?? 8;
+    const w = this._wasm;
+
+    // OR queries: run each branch as its own resumable search, dedup, sort.
+    if (parsed.kind === 'or') {
+      const seen = new Set<string>();
+      const all: SearchResult[] = [];
+      for (const tokens of parsed.branches) {
+        const q = tokensToWasmQuery(tokens);
+        if (!q) continue;
+        const r = await this._runSearchBudgeted(q, query, opts, budget);
+        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);
+      for (const r of all) yield r;
+      return;
+    }
+
+    const results = await this._runSearchBudgeted(tokensToWasmQuery(parsed.tokens), query, opts, budget);
+    const filtered = parsed.kind === 'phrase'
+      ? results.filter(r => containsPhrase(r.snippet, parsed.tokens))
+      : results;
+    for (const r of filtered) yield r;
+    void w;
+  }
+
+  /**
+   * @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.
+   */
+  async *searchStream(query: string, opts: SearchOptions = {}): AsyncIterable<SearchResult> {
+    warnSearchStreamDeprecated();
+    yield* this.searchCooperative(query, opts);
+  }
+
+  /**
+   * Drive a resumable search until done, yielding to the scheduler when the
+   * frame budget is exceeded. Returns the materialised result array.
+   *
+   * Heuristic: each call to `searchSlice` processes a chunk batch, then we
+   * check elapsed time. The batch size doubles up to a cap to amortise the
+   * JS<->WASM overhead on fast machines; on slow machines a single batch
+   * may eat the entire budget, which is also fine.
+   */
+  private async _runSearchBudgeted(
+    wasmQuery: string,
+    displayQuery: string,
+    opts: SearchOptions,
+    budgetMs: number,
+  ): Promise<SearchResult[]> {
+    const w = this._wasm;
+    const ql = this._writeStr(wasmQuery);
+    w.setPattern(ql);
+
+    // 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(wasmQuery);
+      } catch (e) {
+        // Don't let a GPU hiccup kill the search — drop to CPU path.
+        console.warn('[albex] GPU pre-filter failed; falling back to CPU:', e);
+        w.clearCandidateMask();
+      }
+    }
+
+    const t0 = performance.now();
+    if (w.searchBegin() === 0) {
+      this._lastSearch = {
+        query: displayQuery, timeMs: 0, results: 0,
+        bloomTested: 0, bloomPassed: 0, bitapMatched: 0,
+      };
+      return [];
+    }
+
+    // In background / low-power modes we halve the initial batch so the
+    // engine yields more often to the scheduler, leaving more headroom for
+    // whatever the host is doing.
+    const conservative = this._resources?.mode === 'background'
+                      || this._resources?.mode === 'low-power';
+    let batch = conservative ? 1024 : 2048;
+    // `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);
+  }
+
+  /** Materialise results [0..count) into the public SearchResult shape. */
+  private _collectResults(count: number, opts: SearchOptions): SearchResult[] {
+    const w = this._wasm;
+    const windowed = opts.windowed === true;
+    const before   = opts.before ?? 60;
+    const after    = opts.after  ?? 120;
+
+    const results: SearchResult[] = [];
+    for (let i = 0; i < count; i++) {
+      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, opts: SearchOptions): SearchResult[] {
     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 results = this._runSearch(q, 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); }
@@ -496,35 +1992,79 @@ export class AlbexEngine {
     return all;
   }
 
-  private _runSearch(wasmQuery: string, displayQuery: string): SearchResult[] {
-    const ql  = this._writeStr(wasmQuery);
-    (this._wasm.setPattern as Function)(ql);
+  private _runSearch(wasmQuery: string, displayQuery: string, opts: SearchOptions): SearchResult[] {
+    const w  = this._wasm;
+    const ql = this._writeStr(wasmQuery);
+    w.setPattern(ql);
 
     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 windowed = opts.windowed === true;
+    const before   = opts.before ?? 60;
+    const after    = opts.after  ?? 120;
+
     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 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 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 });
+      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();
+        // Spans came back chunk-relative; shift them into window-relative.
+        // Account for leading "... " prefix when present.
+        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;
   }
@@ -532,11 +2072,14 @@ export class AlbexEngine {
   /** 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 +2100,193 @@ 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._wasm.init();
+    this._docs = [];
+    this._lastSearch = 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> {
+    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> {
+    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;
+    }
+
+    // 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> {
+    const loaded = await this.load(name);
+    if (!loaded) this.reset();
+    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 {
+    this.reset();
+    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;
   }
 }