albex 0.3.0 → 0.6.1

package/dist/wasm-bindings.js

@@ -1,5 +1,5 @@
 /*!
- * albex v0.3.0
+ * albex v0.6.1
  * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
  * (c) 2026 RafaCalRob
  * @license MIT
@@ -17,17 +17,120 @@
  * in `wasm/src/lib.rs` and `pdf-wasm/src/lib.rs`.
  */
 // ─────────────────────────────────────────────────────────────────────────────
-// Narrowing helpers for instantiation results
+// Runtime validators
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Cast `WebAssembly.Exports` to the typed Albex main interface.
- * Runtime check is intentionally minimal — if the .wasm doesn't match,
- * the first call site that touches a missing function throws naturally.
- */
+//
+// These replace the pre-0.5.0 `as unknown as` casts. They check three
+// things at instantiation time:
+//   1. memory is a WebAssembly.Memory instance.
+//   2. abiVersion() returns a number inside the supported range.
+//   3. every required export exists and is a function.
+//
+// If any of these fails, the loader throws a typed error before the
+// engine returns from init(). This eliminates the audit 3.2 issue:
+// previously a missing export only surfaced when its call site ran.
+/** Range of ABI versions this host code understands for the main module.
+ * Update both ends together with the Rust `abiVersion()` constant when
+ * the export surface changes. */
+// ABI 7 adds runtime capacity (initWithCapacity, decision A16) and removes
+// the compile-time tier system (`getTier` is gone), on top of ABI 6's batch
+// frontier reads, ABI 5's truncation signalling and ABI 4's authoritative
+// chunk enumeration. The required-exports list below already makes any
+// older binary fail the missing-exports check, so a tolerant lower bound
+// was dead code — the range is pinned to the one ABI this host actually
+// speaks (audit 0.6.0, finding #7). The .wasm ships inside this package
+// (files: wasm/pkg/*.wasm), so host TS and binary are always
+// version-matched.
+const MAIN_ABI_MIN = 7;
+const MAIN_ABI_MAX = 7;
+/** Range of ABI versions for the PDF module. */
+const PDF_ABI_MIN = 1;
+const PDF_ABI_MAX = 3;
+/** Required function names on the main WASM. Adding a new one here forces
+ * the validator to check it; removing one is a breaking ABI bump. */
+const MAIN_REQUIRED = [
+    'abiVersion', 'getBuffer', 'init', 'initWithCapacity',
+    'setDocumentName', 'beginDocument', 'feedXmlBytes', 'endDocument',
+    'beginXlsx', 'feedXlsxBytes',
+    'feedText', 'flushParagraph',
+    'setMaxErrors', 'setThreshold', 'setMaxResults',
+    'prepareQuery', 'getQueryKind', 'getQueryBranchCount',
+    'getQueryBranchPattern', 'selectQueryBranch', 'getQueryTruncationFlags',
+    'setPattern', 'search',
+    'searchBegin', 'searchSlice', 'getSearchCursor', 'getSearchTotal',
+    'getResultCount', 'getResultsPtr', 'getResultStride',
+    'getResultDocId', 'getResultLocation', 'getResultScore',
+    'getResultStart', 'getResultEnd', 'getResultChunkIdx',
+    'getResultDocName', 'getResultMatchCount',
+    'getResultMatchStartAt', 'getResultMatchEndAt',
+    'getSnippet', 'getSnippetWindow', 'getSnippetWindowOffset',
+    'getStatBloomTested', 'getStatBloomPassed', 'getStatBitapMatched',
+    'getChunkCount', 'getDocCount', 'getTextUsed', 'getTextCapacity',
+    'getLastIndexOverflow',
+    'snapshotSize', 'snapshotChunk',
+    'restoreBegin', 'restoreFeed', 'restoreCommit',
+    'getDocId', 'getDocChunkCount', 'getDocName', 'isDocDeleted',
+    'removeDocument', 'compact',
+    'getDocChunkBase', 'getChunkLocationAt', 'getChunkByteLenAt', 'getChunkTextAt',
+    'listChunksBatch',
+    'setLanguage',
+    'getMaxChunks', 'getMaxDocs', 'getNameCapacity',
+    'getChunksPtr', 'getChunkStructSize',
+    'setCandidateMask', 'clearCandidateMask',
+    'getPatternBloomLo', 'getPatternBloomHi',
+    'getDocContentHashPtr', 'getDocContentHashLen', 'setDocumentContentHash',
+    'hashBegin', 'hashFeed', 'hashFinish',
+];
+const PDF_REQUIRED = [
+    'abiVersion', 'allocInput', 'extractPdf',
+    'getPageLen', 'getPagePtr', 'getErrorLen', 'getErrorPtr',
+    'getPageCount', 'extractPageImages',
+    'getPageImageLen', 'getPageImagePtr', 'getPageImageKind',
+];
+/** Thrown when an instantiated WASM module fails the ABI contract. */
+export class AlbexAbiMismatchError extends Error {
+    module;
+    missing;
+    version;
+    constructor(module, message, opts) {
+        super(message);
+        this.name = 'AlbexAbiMismatchError';
+        this.module = module;
+        if (opts?.missing)
+            this.missing = opts.missing;
+        if (opts?.version !== undefined)
+            this.version = opts.version;
+    }
+}
+function validateExports(exports, required, module, abiMin, abiMax) {
+    const mem = exports['memory'];
+    if (!(mem instanceof WebAssembly.Memory)) {
+        throw new AlbexAbiMismatchError(module, `${module}: \`memory\` is missing or not a WebAssembly.Memory instance.`);
+    }
+    const missing = [];
+    for (const name of required) {
+        if (typeof exports[name] !== 'function')
+            missing.push(name);
+    }
+    if (missing.length) {
+        throw new AlbexAbiMismatchError(module, `${module}: WASM binary missing required exports: ${missing.join(', ')}. ` +
+            `The .wasm was built with an incompatible source — rebuild with the current toolchain.`, { missing });
+    }
+    const version = exports['abiVersion']();
+    if (version < abiMin || version > abiMax) {
+        throw new AlbexAbiMismatchError(module, `${module}: abiVersion ${version} outside supported range [${abiMin}..${abiMax}]. ` +
+            `The host TypeScript expects a different binary — upgrade albex or rebuild the WASM.`, { version });
+    }
+}
+/** Validate and narrow `WebAssembly.Exports` to the typed Albex main
+ * interface. Throws `AlbexAbiMismatchError` if the contract is broken. */
 export function asAlbexExports(exports) {
+    validateExports(exports, MAIN_REQUIRED, 'main', MAIN_ABI_MIN, MAIN_ABI_MAX);
     return exports;
 }
+/** Validate and narrow `WebAssembly.Exports` to the typed PDF interface. */
 export function asAlbexPdfExports(exports) {
+    validateExports(exports, PDF_REQUIRED, 'pdf', PDF_ABI_MIN, PDF_ABI_MAX);
     return exports;
 }
 //# sourceMappingURL=wasm-bindings.js.map

package/dist/wasm-bindings.js.map

@@ -1 +1 @@
-{"version":3,"file":"wasm-bindings.js","sourceRoot":"","sources":["../src/wasm-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8KH,gFAAgF;AAChF,8CAA8C;AAC9C,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAA4B;IACzD,OAAO,OAAsC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,OAAO,OAAqC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"wasm-bindings.js","sourceRoot":"","sources":["../src/wasm-bindings.ts"],"names":[],"mappings":"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"}

package/dist/worker-protocol.d.ts

@@ -9,7 +9,7 @@
  * `Transferable` is opt-in per op; we use it for `indexFile` to avoid
  * copying the file bytes into the worker.
  */
-import type { AlbexOptions, IndexedDocument, SearchOptions, SearchResult, EngineStats, SearchStats } from './albex.js';
+import type { AlbexDiagnostic, AlbexOptions, AuthoritativeChunk, IndexedDocument, SearchOptions, SearchResult, EngineStats, SearchStats } from './albex.js';
 export type WorkerOp = {
     kind: 'init';
     opts: AlbexOptions;
@@ -21,9 +21,23 @@ export type WorkerOp = {
     kind: 'search';
     query: string;
     options: SearchOptions;
+} | {
+    kind: 'listChunks';
+    docId: number;
 } | {
     kind: 'removeDocument';
     id: string;
+}
+/** Replace doc `name` with new content. `fileName` is the replacement
+ * file's own name (may differ from `name`); the bytes travel as a
+ * transferred ArrayBuffer like `indexFile`. */
+ | {
+    kind: 'replaceDocument';
+    name: string;
+    fileName: string;
+    buffer: ArrayBuffer;
+} | {
+    kind: 'takeDiagnostics';
 } | {
     kind: 'compact';
 } | {
@@ -69,18 +83,25 @@ export type WorkerResponse = {
     id: number;
     ok: true;
     result: unknown;
-} | {
+}
+/** `limit`/`max` are populated for capacity errors so the rehydrated
+ * AlbexCapacityError keeps reporting the runtime limit that overflowed. */
+ | {
     id: number;
     ok: false;
     error: {
         name: string;
         kind?: string;
         message: string;
+        limit?: string;
+        max?: number;
     };
 };
 export type IndexFileResult = IndexedDocument;
 export type SearchResultArr = SearchResult[];
+export type ChunksResult = AuthoritativeChunk[];
 export type StatsResult = EngineStats;
 export type SearchStatsRes = SearchStats | null;
 export type DocsResult = readonly IndexedDocument[];
+export type DiagnosticsRes = AlbexDiagnostic[];
 //# sourceMappingURL=worker-protocol.d.ts.map

package/dist/worker-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["../src/worker-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAY,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAQ,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAW,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAG,EAAE,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAM,IAAI,EAAE,KAAK,GAAG,IAAI,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAa,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAa,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAO,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAG,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG,eAAe,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,YAAY,EAAE,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAO,WAAW,CAAC;AAC1C,MAAM,MAAM,cAAc,GAAI,WAAW,GAAG,IAAI,CAAC;AACjD,MAAM,MAAM,UAAU,GAAQ,SAAS,eAAe,EAAE,CAAC"}
+{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["../src/worker-protocol.ts"],"names":[],"mappings":"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"}

package/dist/worker-protocol.js

@@ -1,5 +1,5 @@
 /*!
- * albex v0.3.0
+ * albex v0.6.1
  * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
  * (c) 2026 RafaCalRob
  * @license MIT

package/dist/worker-runtime.js

@@ -1,5 +1,5 @@
 /*!
- * albex v0.3.0
+ * albex v0.6.1
  * Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.
  * (c) 2026 RafaCalRob
  * @license MIT
@@ -39,8 +39,18 @@ async function dispatch(op) {
         }
         case 'search':
             return ensureEngine().search(op.query, op.options);
+        case 'listChunks':
+            return ensureEngine().listChunks(op.docId);
         case 'removeDocument':
             return ensureEngine().removeDocument(op.id);
+        case 'replaceDocument': {
+            // Same File-like wrapping as indexFile; the engine's replaceDocument
+            // handles remove + re-index + auto-compact under its own lock.
+            const file = new File([op.buffer], op.fileName);
+            return ensureEngine().replaceDocument(op.name, file);
+        }
+        case 'takeDiagnostics':
+            return ensureEngine().takeDiagnostics();
         case 'compact':
             ensureEngine().compact();
             return undefined;
@@ -77,8 +87,8 @@ async function dispatch(op) {
             return ensureEngine().listSnapshots();
     }
 }
-self.onmessage = async (ev) => {
-    const { id, op } = ev.data;
+async function handle(req) {
+    const { id, op } = req;
     try {
         const result = await dispatch(op);
         const res = { id, ok: true, result };
@@ -92,9 +102,23 @@ self.onmessage = async (ev) => {
                 name: e.name ?? 'Error',
                 kind: err instanceof AlbexError ? err.kind : undefined,
                 message: e.message ?? String(err),
+                // Capacity metadata (which pool + its runtime limit) — plain data,
+                // survives structuredClone, lets the main side rehydrate a full
+                // AlbexCapacityError.
+                limit: typeof e.limit === 'string' ? e.limit : undefined,
+                max: typeof e.max === 'number' ? e.max : undefined,
             },
         };
         self.postMessage(res);
     }
+}
+// Process messages strictly in arrival order. The engine guards its own
+// state, but a sync `search` arriving mid-`indexFile` await would otherwise
+// be rejected as "busy"; queueing keeps the worker's externally-observable
+// behaviour serial and matches the main-thread engine's serialization.
+let _queue = Promise.resolve();
+self.onmessage = (ev) => {
+    const req = ev.data;
+    _queue = _queue.then(() => handle(req));
 };
 //# sourceMappingURL=worker-runtime.js.map

package/dist/worker-runtime.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "albex",
-  "version": "0.3.0",
+  "version": "0.6.1",
   "description": "Zero-config local full-text search for documents — runs entirely in the browser, no server, no upload.",
   "type": "module",
   "main": "./dist/albex.js",
@@ -42,18 +42,21 @@
   ],
   "scripts": {
     "build": "tsc && node scripts/banner.mjs",
-    "prepublishOnly": "npm run build",
-    "build:wasm": "node scripts/build-wasm.mjs std && node scripts/wasm-banner.mjs",
-    "build:wasm:mini": "node scripts/build-wasm.mjs mini && node scripts/wasm-banner.mjs",
-    "build:wasm:pro":  "node scripts/build-wasm.mjs pro && node scripts/wasm-banner.mjs",
-    "build:wasm:tiers": "node scripts/build-wasm.mjs && node scripts/wasm-banner.mjs",
-    "build:pdf-wasm": "cd pdf-wasm && cargo build --target wasm32-unknown-unknown --release && cp ../target/wasm32-unknown-unknown/release/albex_pdf.wasm ../wasm/pkg/albex_pdf.wasm && node scripts/wasm-banner.mjs",
-    "build:all": "npm run build:wasm:tiers && npm run build:pdf-wasm && npm run build",
+    "prepublishOnly": "npm run build:all && npm test",
+    "build:wasm": "node scripts/build-wasm.mjs && node scripts/wasm-banner.mjs",
+    "build:wasm:baseline": "node scripts/build-wasm.mjs --no-simd && node scripts/wasm-banner.mjs",
+    "build:pdf-wasm": "node scripts/build-pdf-wasm.mjs && node scripts/wasm-banner.mjs",
+    "build:all": "npm run build:wasm && npm run build:pdf-wasm && npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "bench": "vitest bench --run",
-    "serve": "npx --yes serve@14 -p 5173 -L ."
+    "test:e2e": "playwright test",
+    "build:ocr": "npm --prefix packages/ocr run build",
+    "clean": "node scripts/clean.mjs",
+    "clean:all": "node scripts/clean.mjs --all",
+    "serve": "npx --yes serve@14 -p 5173 -L .",
+    "relaunch": "npm run clean && npm run build:all && npm run build:ocr && npm test && npm pack && node scripts/relaunch-banner.mjs && npm run serve"
   },
   "repository": {
     "type": "git",
@@ -94,6 +97,7 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "typescript": "^5.4.0",
     "vitest": "^2.0.0"
   }

package/src/albex-worker.ts

@@ -20,10 +20,28 @@
  * call is in flight at a time. This matches the actual `static mut` model
  * inside the .wasm and is fine for an interactive search UI (each keystroke
  * replaces the previous query).
+ *
+ * ## OCR is NOT available in the worker
+ *
+ * `AlbexEngineWorker` has no `attachOcr`: an OCR adapter is an object with
+ * functions, and functions cannot cross the `postMessage` boundary (the
+ * structured-clone algorithm rejects them). Consequences:
+ *
+ *  - **Scanned (image-only) PDFs index with 0 chunks, silently.** The
+ *    engine records a diagnostic explaining why — read it with
+ *    {@link takeDiagnostics} after `indexFile`.
+ *  - If your corpus contains scanned PDFs and you need their text, index
+ *    them with the synchronous main-thread `AlbexEngine` plus the OCR
+ *    adapter (`engine.attachOcr(...)` / `@albex/ocr`'s `enableOcr`), then
+ *    `save()` the snapshot and `load()` it from the worker engine.
+ *  - A future protocol iteration could proxy OCR over a dedicated
+ *    `MessagePort`; until then the main-thread engine is the OCR path.
  */
 
 import type {
+  AlbexDiagnostic,
   AlbexOptions,
+  AuthoritativeChunk,
   IndexedDocument,
   SearchOptions,
   SearchResult,
@@ -41,6 +59,7 @@ import {
   AlbexUnsupportedFormatError,
   AlbexParseError,
   AlbexCapacityError,
+  assertFileSizeWithinLimit,
 } from './errors.js';
 
 export interface AlbexWorkerOptions extends AlbexOptions {
@@ -60,12 +79,32 @@ export class AlbexEngineWorker {
   private _worker!: Worker;
   private _nextId = 1;
   private _pending = new Map<number, Pending>();
-  private _docsCache: IndexedDocument[] = [];
 
   constructor(opts: AlbexWorkerOptions) {
     this._opts = opts;
   }
 
+  /**
+   * Spawn the worker and initialise the engine inside it.
+   *
+   * Every serializable engine option is forwarded across the worker
+   * boundary (`wasmUrl`, `wasmBaseUrl`, `pdfWasmUrl`, `capacity`, `simd`,
+   * `gpu`, `gpuThreshold`, `maxFileBytes`) — only `workerUrl`, which is
+   * consumed on this side, is stripped. Notes on what applies in a worker:
+   *
+   *  - `capacity`: fully honoured — both the `'std'`/`'large'` presets
+   *    (plain strings) and a custom object are structured-clone-safe, so
+   *    the worker-side engine sizes its pools exactly like a main-thread
+   *    engine would. Mind the memory cost (`'large'` ≈ 180 MB) lives in
+   *    the worker's heap.
+   *  - `wasmBaseUrl` + `simd`: fully honoured — the worker-side engine can
+   *    load the `_simd.wasm` variant.
+   *  - `gpu` / `gpuThreshold`: honoured where the worker runtime exposes
+   *    WebGPU. `navigator.gpu` is available in dedicated workers in
+   *    Chromium-based browsers (compute needs no canvas); elsewhere the
+   *    engine's GPU probe fails gracefully and searches use the CPU
+   *    pre-filter, exactly as on the main thread.
+   */
   async init(): Promise<void> {
     this._worker = new Worker(this._opts.workerUrl, { type: 'module' });
     this._worker.onmessage = (ev: MessageEvent<WorkerResponse>) => {
@@ -82,10 +121,16 @@ export class AlbexEngineWorker {
       for (const [, p] of this._pending) p.reject(err);
       this._pending.clear();
     };
-    await this._send({ kind: 'init', opts: {
-      wasmUrl:    this._opts.wasmUrl,
-      pdfWasmUrl: this._opts.pdfWasmUrl,
-    } });
+    // Forward every serializable engine option. AlbexOptions is data-only
+    // (strings/numbers/booleans), but filter defensively so a future
+    // non-clonable option (function, DOM handle) cannot break postMessage.
+    const opts: AlbexOptions = {};
+    for (const [k, v] of Object.entries(this._opts)) {
+      if (k === 'workerUrl') continue; // consumed on this side
+      if (v === undefined || typeof v === 'function') continue;
+      (opts as Record<string, unknown>)[k] = v;
+    }
+    await this._send({ kind: 'init', opts });
   }
 
   private _send<T = unknown>(op: WorkerOp, transfer: Transferable[] = []): Promise<T> {
@@ -98,20 +143,31 @@ export class AlbexEngineWorker {
   }
 
   async indexFile(file: File): Promise<IndexedDocument> {
+    // Size guard BEFORE reading: the worker-side engine enforces the same
+    // limit, but checking here avoids buffering an oversized file on the
+    // main thread just to have the worker reject it.
+    assertFileSizeWithinLimit(file, this._opts.maxFileBytes);
     const buffer = await file.arrayBuffer();
     // Transfer the buffer to avoid a copy.
-    const doc = await this._send<IndexedDocument>(
+    return this._send<IndexedDocument>(
       { kind: 'indexFile', name: file.name, buffer },
       [buffer],
     );
-    this._docsCache.push(doc);
-    return doc;
   }
 
   search(query: string, opts: SearchOptions = {}): Promise<SearchResult[]> {
     return this._send<SearchResult[]>({ kind: 'search', query, options: opts });
   }
 
+  /**
+   * Enumerate the authoritative chunks Albex indexed for `docId`
+   * (`IndexedDocument.docId` from {@link indexFile}). Mirrors
+   * `AlbexEngine.listChunks` across the worker boundary.
+   */
+  listChunks(docId: number): Promise<AuthoritativeChunk[]> {
+    return this._send<AuthoritativeChunk[]>({ kind: 'listChunks', docId });
+  }
+
   /**
    * Cooperative variant of `search`. Today the wire still sends a single
    * batch — the result array is fetched in one round-trip from the worker
@@ -137,17 +193,44 @@ export class AlbexEngineWorker {
   }
 
   async removeDocument(id: string): Promise<boolean> {
-    const ok = await this._send<boolean>({ kind: 'removeDocument', id });
-    if (ok) this._docsCache = this._docsCache.filter(d => d.name !== id && d.contentHash !== id);
-    return ok;
+    return this._send<boolean>({ kind: 'removeDocument', id });
   }
 
-  async compact(): Promise<void> { await this._send({ kind: 'compact' }); }
-  async reset(): Promise<void>   {
-    await this._send({ kind: 'reset' });
-    this._docsCache = [];
+  /**
+   * Replace a previously indexed document with new content. Mirrors
+   * `AlbexEngine.replaceDocument`: equivalent to `removeDocument(name)` +
+   * `indexFile(newFile)` without tripping the idempotency check, plus an
+   * opportunistic compact under text-pool pressure — all inside the
+   * worker-side engine's lock. The file bytes are transferred (zero-copy),
+   * like `indexFile`.
+   */
+  async replaceDocument(name: string, newFile: File): Promise<IndexedDocument> {
+    assertFileSizeWithinLimit(newFile, this._opts.maxFileBytes);
+    const buffer = await newFile.arrayBuffer();
+    return this._send<IndexedDocument>(
+      { kind: 'replaceDocument', name, fileName: newFile.name, buffer },
+      [buffer],
+    );
+  }
+
+  /**
+   * Drain and return the diagnostics collected by the worker-side engine
+   * since the last call. Mirrors `AlbexEngine.takeDiagnostics` — consult it
+   * after `indexFile`/`load` to surface recoverable issues (PDF fallbacks,
+   * skipped content, persistence warnings). The worker-side buffer is
+   * cleared on each call.
+   *
+   * Particularly important in a worker: scanned PDFs index with **0 chunks**
+   * (no OCR available — see the note on OCR below), and the diagnostic
+   * explaining why is only visible through this method.
+   */
+  takeDiagnostics(): Promise<AlbexDiagnostic[]> {
+    return this._send<AlbexDiagnostic[]>({ kind: 'takeDiagnostics' });
   }
 
+  async compact(): Promise<void> { await this._send({ kind: 'compact' }); }
+  async reset(): Promise<void>   { await this._send({ kind: 'reset' }); }
+
   getStats():          Promise<EngineStats>       { return this._send({ kind: 'getStats' }); }
   getLastSearchStats(): Promise<SearchStats | null> { return this._send({ kind: 'getLastSearchStats' }); }
   getDocuments():       Promise<readonly IndexedDocument[]> { return this._send({ kind: 'getDocuments' }); }
@@ -168,16 +251,18 @@ export class AlbexEngineWorker {
     for (const [, p] of this._pending) p.reject(new AlbexError('disposed', 'Engine disposed'));
     this._pending.clear();
     this._worker?.terminate();
-    this._docsCache = [];
   }
 }
 
-function rehydrateError(e: { name: string; kind?: string; message: string }): Error {
+function rehydrateError(e: { name: string; kind?: string; message: string; limit?: string; max?: number }): Error {
   switch (e.kind) {
     case 'init':               return new AlbexInitError(e.message);
     case 'unsupported_format': return new AlbexUnsupportedFormatError(e.message.replace(/^Unsupported format: \./, ''));
     case 'parse':              return new AlbexParseError('unknown', e.message);
-    case 'capacity':           return new AlbexCapacityError(e.message);
+    // `limit`/`max` survive the wire (worker-runtime serialises them) so
+    // the rehydrated error still reports the runtime capacity that
+    // overflowed inside the worker-side engine.
+    case 'capacity':           return new AlbexCapacityError(e.message, e.limit as never, e.max);
     default: {
       const err = new Error(e.message);
       err.name = e.name;