albex 0.6.0 → 0.6.1

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;