albex 0.1.0 → 0.6.0

package/dist/albex.d.ts

@@ -13,11 +13,61 @@
  * const results = engine.search('contrato marco');
  * ```
  */
+import { type Tier } from './profile.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';
 export interface AlbexOptions {
-    /** URL to albex_wasm_bg.wasm (required). */
-    wasmUrl: string;
+    /**
+     * Explicit URL to the main WASM binary.
+     *
+     * If you want automatic tier selection (mini/std/pro chosen from
+     * `deviceMemory`), pass `wasmBaseUrl` instead — the engine will fetch
+     * `albex_wasm_<tier>.wasm` from that directory.
+     */
+    wasmUrl?: string;
+    /**
+     * Base directory containing tiered binaries (`albex_wasm_mini.wasm`,
+     * `_std.wasm`, `_pro.wasm`). Used when `wasmUrl` is omitted.
+     */
+    wasmBaseUrl?: string;
     /** URL to albex_pdf.wasm. Required only if you call indexFile() with PDFs. */
     pdfWasmUrl?: string;
+    /**
+     * Override the tier auto-detection. Pass `'auto'` (default), or an
+     * explicit tier when you know the constraints of your target environment.
+     */
+    /** @deprecated Removed in 0.5.0. Albex no longer has capacity tiers;
+     * pass `'auto'` or omit. Other values are accepted and ignored. */
+    tier?: 'auto' | 'mini' | 'std' | 'pro';
+    /**
+     * SIMD selection. When `'auto'` (default), Albex probes for v128 support
+     * and fetches the `_simd.wasm` variant when available. Pass `'off'` to
+     * stay on the baseline binary even on capable hosts (useful for
+     * regression testing or to align all clients in a corporate deployment).
+     */
+    simd?: 'auto' | 'on' | 'off';
+    /**
+     * GPU acceleration policy for the Bloom pre-filter.
+     *   `'auto'`  — enable when WebGPU is available AND chunk count is large
+     *   `'on'`    — force enable (fall back to CPU silently if GPU fails)
+     *   `'off'`   — never use GPU
+     * Default: `'auto'`.
+     */
+    gpu?: 'auto' | 'on' | 'off';
+    /**
+     * Minimum chunk count before `gpu: 'auto'` engages. Below this threshold
+     * the upload + dispatch overhead is bigger than the speedup. Default: 20_000.
+     */
+    gpuThreshold?: number;
 }
 export interface IndexedDocument {
     name: string;
@@ -25,6 +75,16 @@ 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 {
     documentName: string;
@@ -32,12 +92,37 @@ 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 {
     documents: number;
@@ -45,6 +130,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 {
     query: string;
@@ -54,43 +145,355 @@ export interface SearchStats {
     bloomPassed: number;
     bitapMatched: number;
 }
+/**
+ * One structured warning recorded by the engine during indexFile or
+ * load. Replaces the pre-0.5.0 pattern of scattered `console.warn`
+ * calls. Inspect via `engine.takeDiagnostics()` after the operation.
+ */
+export interface AlbexDiagnostic {
+    /** Coarse kind. `'recovered'` means the engine handled the issue and
+     * kept going; `'skipped'` means content was dropped; `'fallback'` means
+     * an alternate code path was used (e.g. lopdf after pdf-extract trap). */
+    kind: 'recovered' | 'skipped' | 'fallback' | 'info';
+    /** Where in the pipeline this happened. Free-form short tag. */
+    stage: 'pdf' | 'ocr' | 'gpu' | 'persistence' | 'network';
+    /** Human-readable message safe to surface in a UI. */
+    message: string;
+    /** Optional file the issue belongs to. */
+    file?: string;
+    /** Optional page number (1-based for PDFs). */
+    page?: number;
+}
+/**
+ * Result shape returned by an attached OCR module. Kept structural here so
+ * the main package has no runtime dependency on `@albex/ocr` — the optional
+ * shape is just a contract.
+ */
+export interface OcrAttachedResult {
+    text: string;
+    confidence: number;
+    timeMs: number;
+}
+export interface OcrAttachedOptions {
+    lang?: string;
+    hint?: string;
+}
+/**
+ * Contract the engine accepts from an OCR plugin. `@albex/ocr` is the
+ * canonical implementation, but any module that satisfies this interface
+ * can be attached via `engine.attachOcr(adapter)`.
+ */
+export interface OcrAdapter {
+    /** Invoked by the engine to OCR a single image. Receives whatever the
+     * caller passes (Blob, ArrayBuffer, etc.); the adapter is responsible
+     * for accepting that input. Must return text + confidence. */
+    recognize(image: unknown, opts?: OcrAttachedOptions): Promise<OcrAttachedResult>;
+    /** Engine-side switches the adapter wants honoured. The only one
+     * defined today is `alwaysExtractEmbeddedImages`, which turns on the
+     * hybrid PDF OCR pass. New flags can be added without breaking the
+     * adapter interface. */
+    options?: {
+        /** When true, every PDF (native or scanned) is walked for embedded
+         * images and each qualifying image is sent to `recognize`. Off by
+         * default to keep performance predictable on native PDFs. */
+        alwaysExtractEmbeddedImages?: boolean;
+    };
+}
+/** Returned by `attachOcr`. Holds the lifecycle handles for the plugin.
+ * Calling `dispose()` removes the adapter from the engine; subsequent
+ * `engine.ocrImage` access returns `undefined` again. */
+export interface OcrHandle {
+    /** Detach the plugin and tear down any resources it holds. After this,
+     * the engine reverts to "no OCR" — scanned PDFs go back to registering
+     * with zero chunks. */
+    dispose(): Promise<void>;
+}
 export declare class AlbexEngine {
     private _wasm;
     private _mem;
+    /**
+     * OCR entry point installed by `@albex/ocr::enableOcr(engine)`. Undefined
+     * when the OCR module has not been wired. The main `albex` package has no
+     * runtime dependency on OCR — this is a structural slot that the optional
+     * companion package fills.
+     */
+    /**
+     * Public OCR entry point. Forwards to the attached OCR adapter installed
+     * via `attachOcr()`. Reading this property is a feature-detect for
+     * integrators: `if (engine.ocrImage) { ... OCR available ... }`. Writing
+     * to it directly is no longer supported in 0.5.0+ — use `attachOcr`.
+     */
+    get ocrImage(): ((image: unknown, opts?: OcrAttachedOptions) => Promise<OcrAttachedResult>) | undefined;
+    /** Private adapter slot. Holds the OCR plugin contract installed by
+     * `attachOcr()`. The engine reads `recognize` and `options` here; the
+     * caller never gets a reference to this object directly. */
+    private _ocrAdapter;
     private _pdfWasm;
     private _pdfMem;
     private _docs;
     private _lastSearch;
+    /** Structured diagnostics collected during the most recent operation.
+     * Drained by `takeDiagnostics()`. Capped at 256 entries to avoid
+     * unbounded memory growth in pathological cases (very corrupted
+     * corpora producing thousands of recovery warnings). */
+    private _diagnostics;
+    private _tier;
+    private _simd;
+    private _profile;
+    private _resources;
+    private _gpu;
+    private _gpuChunkCountUploaded;
+    private _unsubscribeResources;
     private readonly _opts;
+    private _opChain;
+    private _busy;
     constructor(opts: AlbexOptions);
+    /** Serialize an async engine operation behind any in-flight one. */
+    private _exclusive;
+    /** Guard a synchronous mutator/search: refuse to run mid-async-operation
+     * rather than silently corrupt the shared WASM state. */
+    private _assertIdle;
+    /** Compact opportunistically when tombstones pile up under text pressure,
+     * so repeated removeDocument/replaceDocument don't exhaust the pool. */
+    private _autoCompactIfNeeded;
     /** Load and initialise the main WASM module. Must be called before any other method. */
     init(): Promise<void>;
+    /**
+     * 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 _resolveWasmUrl;
+    /** The tier that was actually loaded. `null` until `init()` resolves. */
+    get tier(): Tier | null;
+    /** True if the SIMD-accelerated binary was loaded. */
+    get simdEnabled(): boolean;
+    /** True if a WebGPU device is acquired and the next search will use it. */
+    get gpuEngaged(): boolean;
+    /**
+     * 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;
+    /**
+     * 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 _gpuPreFilter;
     private _u8;
     private _writePad;
     private _writeStr;
     private _readPad;
     private _feedText;
+    /**
+     * Compute the FNV-1a 64-bit content hash of `bytes` via the WASM
+     * streaming API. Returns a 16-character hex string identical in shape
+     * to what the TS implementation in 0.3.x returned, so all callers
+     * stay unchanged. Single source of truth — same hash whether we use
+     * it for indexFile dedup, for snapshot v2 persistence, or anywhere
+     * else. Large inputs are chunked at FEED_SIZE just like _feedText.
+     */
+    private _contentHash;
     private _feedXmlBytes;
     private _ensurePdfWasm;
     private _indexDocx;
     private _indexXlsx;
     private _indexPdf;
+    /**
+     * 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 _indexPdfScanned;
+    /**
+     * 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 _ocrPageEmbeddedImages;
+    /**
+     * 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 _indexPdfViaImagesOnly;
     private _indexTxt;
     private _indexXml;
+    private _indexMd;
+    private _indexHtml;
+    private _indexJson;
+    private _indexCsv;
+    private _indexEml;
+    /**
+     * 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;
+    private _indexRtf;
     private static readonly _INDEXERS;
     /**
      * Index a file. Supported formats: DOCX, XLSX, PDF, TXT, XML.
      * Throws for unsupported formats or parse errors.
      */
     indexFile(file: File): Promise<IndexedDocument>;
+    private _indexFileInner;
+    /**
+     * 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;
+    private _removeDocumentInner;
+    /**
+     * 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).
+     */
+    replaceDocument(name: string, newFile: File): Promise<IndexedDocument>;
+    /**
+     * 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;
     /**
      * Search the index. Supports:
      * - Simple queries:  `contrato`  (AND of tokens, accent-insensitive)
      * - Phrase queries:  `"contrato marco"`  (must appear as phrase)
      * - OR queries:      `contrato | acuerdo`  (union of two searches)
+     *
+     * Pass `{ windowed: true }` to receive cropped snippets with ASCII ellipsis
+     * markers instead of full chunk text. Defaults: 60 bytes before, 120 after.
+     */
+    search(query: string, opts?: SearchOptions): SearchResult[];
+    /** Read the WASM-compiled tokens of branch `i` for phrase post-filter.
+     * The bytes returned are exactly what the WASM tokenizer produced —
+     * no TS re-tokenization. */
+    private _branchTokens;
+    /**
+     * 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).
+     */
+    searchCooperative(query: string, opts?: SearchOptions): AsyncIterable<SearchResult>;
+    /** Materialise a cooperative search to a sorted result array. Runs inside
+     * the exclusivity lock. Frame-budget yielding lives in _runSearchBudgeted. */
+    private _searchCooperativeCollect;
+    /**
+     * @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.
+     */
+    searchStream(query: string, opts?: SearchOptions): AsyncIterable<SearchResult>;
+    /**
+     * 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.
      */
-    search(query: string): SearchResult[];
+    private _runSearchBudgeted;
+    /** Materialise results [0..count) into the public SearchResult shape.
+     * When `phraseTokens` is given, each result is kept only if those tokens
+     * appear adjacently in the FULL chunk text — independent of any display
+     * windowing — so phrase queries stay correct under `{ windowed: true }`. */
+    private _collectResults;
+    /** Run all OR branches and merge dedup-by-(doc, location, match). The
+     * branches are already compiled inside the WASM (by prepareQuery); we
+     * iterate them with selectQueryBranch. The "rawQuery" param is kept
+     * only for the lastSearch.query field. */
     private _searchOr;
+    /** Execute a single search using whichever query branch is currently
+     * active (set via selectQueryBranch). Returns the materialised
+     * SearchResult[]. Caller is responsible for activating a branch first. */
     private _runSearch;
     /** Returns current engine statistics. */
     getStats(): EngineStats;
@@ -104,7 +507,106 @@ export declare class AlbexEngine {
     setMaxErrors(errors: 0 | 1 | 2 | 3): void;
     setThreshold(threshold: number): void;
     setMaxResults(max: number): void;
+    /**
+     * 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;
     /** Full reset — clears all indexed documents and chunks. */
     reset(): void;
+    private _resetInner;
+    /**
+     * Drain and return the diagnostics collected since the last call (or
+     * since the engine was created). Use this to surface recoverable
+     * issues to the caller after `indexFile`, `load`, or any other
+     * operation that may run into a "best-effort" path.
+     *
+     * Example diagnostics:
+     *   - `{kind:'fallback', stage:'pdf', message:'pdf-extract crashed,
+     *      attempting OCR-only fallback', file:'invoice.pdf'}`
+     *   - `{kind:'skipped', stage:'ocr', message:'Tesseract abort on page
+     *      3 image 1; remaining images on this page skipped', file:'...',
+     *      page:3}`
+     *   - `{kind:'fallback', stage:'gpu', message:'GPU pre-filter failed,
+     *      using CPU'}`
+     *
+     * The buffer is cleared on each call; callers should consume the
+     * returned array immediately (e.g. log to their telemetry, surface
+     * a UI banner). After `reset()` the buffer is also cleared.
+     */
+    takeDiagnostics(): AlbexDiagnostic[];
+    /** Internal: record a diagnostic. Capped at 256 to bound memory. */
+    private _diag;
+    /**
+     * Install an OCR adapter. Returns a handle whose `dispose()` removes the
+     * adapter from the engine.
+     *
+     * The contract: the adapter must provide `recognize(image, opts)` that
+     * returns `Promise<OcrAttachedResult>`. The engine validates the
+     * contract at attach time and refuses adapters that don't expose a
+     * recognise function. Only one adapter can be attached at a time; a
+     * second call to `attachOcr` while one is active throws — the caller
+     * must dispose the previous one first.
+     *
+     * @example
+     * ```ts
+     * import { enableOcr } from '@albex/ocr';
+     * const handle = enableOcr(engine);   // internally calls attachOcr
+     * // ... later ...
+     * await handle.dispose();
+     * ```
+     *
+     * Direct use without the companion package:
+     * ```ts
+     * const handle = engine.attachOcr({
+     *   recognize: async (blob) => myCustomOcr(blob),
+     *   options: { alwaysExtractEmbeddedImages: false },
+     * });
+     * ```
+     */
+    attachOcr(adapter: OcrAdapter): OcrHandle;
+    /**
+     * 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.
+     */
+    save(name: string): Promise<void>;
+    private _saveInner;
+    /**
+     * 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).
+     */
+    load(name: string): Promise<boolean>;
+    private _loadInner;
+    /**
+     * Convenience: load if the snapshot exists, otherwise leave the engine
+     * empty. Returns whether a load actually happened.
+     */
+    loadOrInit(name: string): Promise<boolean>;
+    /** Delete a previously persisted snapshot. */
+    deleteSnapshot(name: string): Promise<void>;
+    /** List names of persisted snapshots in the current origin. */
+    listSnapshots(): Promise<string[]>;
+    /**
+     * 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;
 }
 //# sourceMappingURL=albex.d.ts.map

package/dist/albex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"albex.d.ts","sourceRoot":"","sources":["../src/albex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAsLD,qBAAa,WAAW;IAEtB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,IAAI,CAAsB;IAGlC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,OAAO,CAAmC;IAElD,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,IAAI,EAAE,YAAY;IAI9B,wFAAwF;IAClF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,aAAa;YAUP,cAAc;YAad,UAAU;YASV,UAAU;YAqBV,SAAS;YAuCT,SAAS;YAWT,SAAS;IAevB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAM/B;IAIF;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC;IAmBrD;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;IAgBrC,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,UAAU;IAiClB,yCAAyC;IACzC,QAAQ,IAAI,WAAW;IAUvB,0DAA0D;IAC1D,kBAAkB,IAAI,WAAW,GAAG,IAAI;IAIxC,6CAA6C;IAC7C,IAAI,SAAS,IAAI,SAAS,eAAe,EAAE,CAE1C;IAED,iCAAiC;IACjC,MAAM,KAAK,mBAAmB,IAAI,MAAM,EAAE,CAEzC;IAED,oCAAoC;IACpC,YAAY,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI;IAIzC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,4DAA4D;IAC5D,KAAK,IAAI,IAAI;CAKd"}
+{"version":3,"file":"albex.d.ts","sourceRoot":"","sources":["../src/albex.ts"],"names":[],"mappings":"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"}