web-doc 0.5.0 → 0.6.0

package/THIRD_PARTY_NOTICES.md

@@ -4,6 +4,7 @@ The release artifact contains or depends on the following principal components.
 
 - [`@silurus/ooxml`](https://github.com/yukiyokotani/office-open-xml-viewer) — MIT; modern Office parsing/rendering.
 - [`office_oxide`](https://github.com/yfedoseev/office_oxide) — MIT OR Apache-2.0; compound-file handling, Office IR/writer utilities and legacy XLS/PPT conversion.
+- [`Fuse.js`](https://github.com/krisk/Fuse) — Apache-2.0; fuzzy matching behind the opt-in `search()` fallback.
 - [`pdfjs-dist` / Mozilla PDF.js](https://github.com/mozilla/pdf.js) — Apache-2.0; browser PDF parsing,
   font/CMap handling, canvas rendering, and text extraction. The packaged
   standard-font, ICC, CMap, OpenJPEG, JBIG2, and QCMS assets retain the license

package/dist/contracts.d.ts

@@ -257,6 +257,13 @@ export interface FuzzySearchOptions {
      * hint every page in range is scanned. Default `12`.
      */
     readonly pageWindow?: number;
+    /**
+     * Run the matcher in a Web Worker that keeps the document's index, so a
+     * long scan never blocks the page and repeated citation lookups reuse the
+     * index. Falls back to the main thread where workers are unavailable or
+     * the worker script cannot be loaded. Default `true`.
+     */
+    readonly worker?: boolean;
 }
 export interface SearchOptions {
     readonly caseSensitive?: boolean;

package/dist/fuzzy-search-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fuzzy-search-worker.js

@@ -0,0 +1,6 @@
+import { handleFuzzyWorkerRequest, } from "./fuzzy-worker-protocol.js";
+const workerScope = self;
+const state = {};
+workerScope.onmessage = (event) => {
+    workerScope.postMessage(handleFuzzyWorkerRequest(state, event.data));
+};

package/dist/fuzzy-search.d.ts

@@ -14,6 +14,7 @@ export interface ResolvedFuzzySearchOptions {
     readonly maxPageTextLength: number;
     readonly pagesPerBatch: number;
     readonly pageWindow: number;
+    readonly worker: boolean;
 }
 export declare const DEFAULT_FUZZY_SEARCH_OPTIONS: ResolvedFuzzySearchOptions;
 /**
@@ -28,9 +29,30 @@ export interface FuzzyPageText {
     readonly text: string;
 }
 /**
- * One match per page whose text holds the query within the edit budget: the
- * span from the first to the last matched character, so the highlight covers
- * the passage as one block. Pages are returned in page order.
+ * A document's pages, indexed once for Fuse.js so that every fuzzy search
+ * reuses the normalized records instead of rebuilding them: a citation
+ * lookup tries several anchors in a row, and each used to pay for the index
+ * again. A scan restricted to a page window reuses the same records through
+ * `Fuse.parseIndex`, so only the Bitap pass runs for those pages.
+ */
+export declare class FuzzyPageIndex {
+    #private;
+    constructor(pages: readonly FuzzyPageText[], options: {
+        threshold: number;
+        maxPageTextLength: number;
+    }, caseSensitive?: boolean);
+    get pageCount(): number;
+    /**
+     * One match per page whose text holds the query within the edit budget:
+     * the span from the first to the last matched character, so the highlight
+     * covers the passage as one block. `pageIndices` restricts the scan; the
+     * result is in page order either way.
+     */
+    search(query: string, maxScore: number, pageIndices?: readonly number[]): readonly SearchMatch[];
+}
+/**
+ * One-off scan of a few pages, for callers without a standing index. The
+ * viewer keeps a {@link FuzzyPageIndex} per document instead.
  */
 export declare function findFuzzyPageMatches(pages: readonly FuzzyPageText[], query: string, options: ResolvedFuzzySearchOptions, caseSensitive?: boolean): readonly SearchMatch[];
 /** Page indices of `[first, last]` ordered by distance from `nearPage`, ties earlier-first. */

package/dist/fuzzy-search.js

@@ -1,4 +1,4 @@
-import Fuse from "fuse.js";
+import Fuse, {} from "fuse.js";
 export const DEFAULT_FUZZY_SEARCH_OPTIONS = Object.freeze({
     threshold: 0.3,
     maxScore: 0.4,
@@ -8,6 +8,7 @@ export const DEFAULT_FUZZY_SEARCH_OPTIONS = Object.freeze({
     maxPageTextLength: 20_000,
     pagesPerBatch: 2,
     pageWindow: 12,
+    worker: true,
 });
 /**
  * Layer fuzzy settings in precedence order (viewer defaults first, then the
@@ -33,24 +34,14 @@ export function resolveFuzzySearchOptions(...layers) {
             maxPageTextLength: positiveInteger(layer.maxPageTextLength, resolved.maxPageTextLength),
             pagesPerBatch: positiveInteger(layer.pagesPerBatch, resolved.pagesPerBatch),
             pageWindow: positiveInteger(layer.pageWindow, resolved.pageWindow),
+            worker: layer.worker ?? resolved.worker,
         };
     }
     return enabled ? resolved : undefined;
 }
-/**
- * One match per page whose text holds the query within the edit budget: the
- * span from the first to the last matched character, so the highlight covers
- * the passage as one block. Pages are returned in page order.
- */
-export function findFuzzyPageMatches(pages, query, options, caseSensitive = false) {
-    const pattern = query.slice(0, options.maxQueryLength);
-    if (!pattern.trim())
-        return [];
-    const items = pages.map((page) => ({
-        pageIndex: page.pageIndex,
-        text: page.text.slice(0, options.maxPageTextLength),
-    }));
-    const fuse = new Fuse(items, {
+/** Fuse.js options shared by every fuzzy scan; `keys` and `threshold` are fixed per index. */
+function fuseOptions(threshold, caseSensitive) {
+    return {
         keys: ["text"],
         isCaseSensitive: caseSensitive,
         ignoreDiacritics: false,
@@ -61,27 +52,76 @@ export function findFuzzyPageMatches(pages, query, options, caseSensitive = fals
         ignoreLocation: true,
         // Long page text must not dilute the score of a match inside it.
         ignoreFieldNorm: true,
-        threshold: options.threshold,
+        threshold,
         minMatchCharLength: 3,
         shouldSort: false,
-    });
-    const matches = [];
-    for (const result of fuse.search(pattern)) {
-        if ((result.score ?? 1) > options.maxScore)
-            continue;
-        const indices = result.matches?.[0]?.indices ?? [];
-        if (indices.length === 0)
-            continue;
-        let start = Number.POSITIVE_INFINITY;
-        let end = 0;
-        for (const [first, last] of indices) {
-            start = Math.min(start, first);
-            end = Math.max(end, last + 1);
+    };
+}
+/**
+ * A document's pages, indexed once for Fuse.js so that every fuzzy search
+ * reuses the normalized records instead of rebuilding them: a citation
+ * lookup tries several anchors in a row, and each used to pay for the index
+ * again. A scan restricted to a page window reuses the same records through
+ * `Fuse.parseIndex`, so only the Bitap pass runs for those pages.
+ */
+export class FuzzyPageIndex {
+    #pages;
+    #index;
+    #options;
+    #fuse;
+    constructor(pages, options, caseSensitive = false) {
+        this.#pages = pages.map((page) => ({
+            pageIndex: page.pageIndex,
+            text: page.text.slice(0, options.maxPageTextLength),
+        }));
+        this.#options = fuseOptions(options.threshold, caseSensitive);
+        this.#index = Fuse.createIndex(["text"], this.#pages);
+        this.#fuse = new Fuse(this.#pages, this.#options, this.#index);
+    }
+    get pageCount() {
+        return this.#pages.length;
+    }
+    /**
+     * One match per page whose text holds the query within the edit budget:
+     * the span from the first to the last matched character, so the highlight
+     * covers the passage as one block. `pageIndices` restricts the scan; the
+     * result is in page order either way.
+     */
+    search(query, maxScore, pageIndices) {
+        if (!query.trim())
+            return [];
+        const fuse = pageIndices ? this.#subset(pageIndices) : this.#fuse;
+        const matches = [];
+        for (const result of fuse.search(query)) {
+            if ((result.score ?? 1) > maxScore)
+                continue;
+            const indices = result.matches?.[0]?.indices ?? [];
+            if (indices.length === 0)
+                continue;
+            let start = Number.POSITIVE_INFINITY;
+            let end = 0;
+            for (const [first, last] of indices) {
+                start = Math.min(start, first);
+                end = Math.max(end, last + 1);
+            }
+            const text = result.item.text.slice(start, end);
+            matches.push({ pageIndex: result.item.pageIndex, start, end, text });
         }
-        const text = result.item.text.slice(start, end);
-        matches.push({ pageIndex: result.item.pageIndex, start, end, text });
+        return matches.sort((a, b) => a.pageIndex - b.pageIndex);
     }
-    return matches.sort((a, b) => a.pageIndex - b.pageIndex);
+    #subset(pageIndices) {
+        const wanted = new Set(pageIndices);
+        const { keys, records } = this.#index.toJSON();
+        const kept = records.filter((record) => wanted.has(this.#pages[record.i]?.pageIndex ?? -1));
+        return new Fuse(this.#pages, this.#options, Fuse.parseIndex({ keys, records: kept }));
+    }
+}
+/**
+ * One-off scan of a few pages, for callers without a standing index. The
+ * viewer keeps a {@link FuzzyPageIndex} per document instead.
+ */
+export function findFuzzyPageMatches(pages, query, options, caseSensitive = false) {
+    return new FuzzyPageIndex(pages, options, caseSensitive).search(query.slice(0, options.maxQueryLength), options.maxScore);
 }
 /** Page indices of `[first, last]` ordered by distance from `nearPage`, ties earlier-first. */
 export function pagesNearestFirst(first, last, nearPage) {

package/dist/fuzzy-worker-client.d.ts

@@ -0,0 +1,28 @@
+import type { SearchMatch } from "./contracts.js";
+import type { FuzzyPageText } from "./fuzzy-search.js";
+import type { FuzzyWorkerReply, FuzzyWorkerRequest } from "./fuzzy-worker-protocol.js";
+/** The slice of `Worker` the client needs; tests pass a fake. */
+export interface FuzzyWorkerTransport {
+    postMessage(message: FuzzyWorkerRequest): void;
+    addEventListener(type: "message", listener: (event: MessageEvent<FuzzyWorkerReply>) => void): void;
+    addEventListener(type: "error", listener: (event: Event) => void): void;
+    terminate(): void;
+}
+/**
+ * Main-thread side of the fuzzy-search worker. Bitap over a long document
+ * is CPU work that used to run on the main thread and freeze the page; the
+ * worker keeps the document's index and answers each search off-thread.
+ */
+export declare class FuzzyWorkerClient {
+    #private;
+    constructor(worker: FuzzyWorkerTransport);
+    /** Spawn the bundled worker script; `undefined` where workers do not exist. */
+    static create(workerUrl: URL): FuzzyWorkerClient | undefined;
+    index(pages: readonly FuzzyPageText[], options: {
+        readonly threshold: number;
+        readonly maxPageTextLength: number;
+        readonly caseSensitive: boolean;
+    }): Promise<number>;
+    search(query: string, maxScore: number, pageIndices?: readonly number[]): Promise<readonly SearchMatch[]>;
+    terminate(): void;
+}

package/dist/fuzzy-worker-client.js

@@ -0,0 +1,75 @@
+import { ViewerError } from "./errors.js";
+/**
+ * Main-thread side of the fuzzy-search worker. Bitap over a long document
+ * is CPU work that used to run on the main thread and freeze the page; the
+ * worker keeps the document's index and answers each search off-thread.
+ */
+export class FuzzyWorkerClient {
+    #worker;
+    #pending = new Map();
+    #nextId = 1;
+    #dead;
+    constructor(worker) {
+        this.#worker = worker;
+        worker.addEventListener("message", (event) => {
+            const pending = this.#pending.get(event.data.id);
+            if (!pending)
+                return;
+            this.#pending.delete(event.data.id);
+            pending.resolve(event.data);
+        });
+        worker.addEventListener("error", (event) => {
+            this.#fail(new ViewerError("worker-crashed", "Fuzzy search worker crashed", {
+                details: { message: event.message },
+            }));
+        });
+    }
+    /** Spawn the bundled worker script; `undefined` where workers do not exist. */
+    static create(workerUrl) {
+        if (typeof Worker === "undefined")
+            return undefined;
+        return new FuzzyWorkerClient(new Worker(workerUrl, { type: "module", name: "fuzzy-search" }));
+    }
+    async index(pages, options) {
+        const reply = await this.#send({ kind: "index", id: 0, pages, ...options });
+        if (reply.kind !== "indexed")
+            throw unexpected(reply);
+        return reply.pageCount;
+    }
+    async search(query, maxScore, pageIndices) {
+        const reply = await this.#send({
+            kind: "search",
+            id: 0,
+            query,
+            maxScore,
+            ...(pageIndices ? { pageIndices } : {}),
+        });
+        if (reply.kind !== "matches")
+            throw unexpected(reply);
+        return reply.matches;
+    }
+    terminate() {
+        this.#fail(new ViewerError("lifecycle-error", "Fuzzy search worker was terminated"));
+        this.#worker.terminate();
+    }
+    #send(request) {
+        if (this.#dead)
+            return Promise.reject(this.#dead);
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            this.#worker.postMessage({ ...request, id });
+        });
+    }
+    #fail(error) {
+        this.#dead = error;
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+    }
+}
+function unexpected(reply) {
+    return new ViewerError("render-failed", reply.kind === "failure"
+        ? reply.message
+        : `Unexpected worker reply: ${reply.kind}`);
+}

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

@@ -0,0 +1,39 @@
+import type { SearchMatch } from "./contracts.js";
+import { FuzzyPageIndex, type FuzzyPageText } from "./fuzzy-search.js";
+/**
+ * Messages between the viewer and the fuzzy-search worker. The worker holds
+ * one {@link FuzzyPageIndex} at a time: `index` replaces it, `search` runs
+ * against it. Every request is answered by exactly one reply with its `id`.
+ */
+export type FuzzyWorkerRequest = {
+    readonly kind: "index";
+    readonly id: number;
+    readonly pages: readonly FuzzyPageText[];
+    readonly threshold: number;
+    readonly maxPageTextLength: number;
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: "search";
+    readonly id: number;
+    readonly query: string;
+    readonly maxScore: number;
+    readonly pageIndices?: readonly number[];
+};
+export type FuzzyWorkerReply = {
+    readonly kind: "indexed";
+    readonly id: number;
+    readonly pageCount: number;
+} | {
+    readonly kind: "matches";
+    readonly id: number;
+    readonly matches: readonly SearchMatch[];
+} | {
+    readonly kind: "failure";
+    readonly id: number;
+    readonly message: string;
+};
+export interface FuzzyWorkerState {
+    index?: FuzzyPageIndex;
+}
+/** Apply one request to the worker's state and produce its reply. */
+export declare function handleFuzzyWorkerRequest(state: FuzzyWorkerState, request: FuzzyWorkerRequest): FuzzyWorkerReply;

package/dist/fuzzy-worker-protocol.js

@@ -0,0 +1,35 @@
+import { FuzzyPageIndex } from "./fuzzy-search.js";
+/** Apply one request to the worker's state and produce its reply. */
+export function handleFuzzyWorkerRequest(state, request) {
+    try {
+        if (request.kind === "index") {
+            state.index = new FuzzyPageIndex(request.pages, {
+                threshold: request.threshold,
+                maxPageTextLength: request.maxPageTextLength,
+            }, request.caseSensitive);
+            return {
+                kind: "indexed",
+                id: request.id,
+                pageCount: state.index.pageCount,
+            };
+        }
+        if (!state.index)
+            return {
+                kind: "failure",
+                id: request.id,
+                message: "No document is indexed",
+            };
+        return {
+            kind: "matches",
+            id: request.id,
+            matches: state.index.search(request.query, request.maxScore, request.pageIndices),
+        };
+    }
+    catch (error) {
+        return {
+            kind: "failure",
+            id: request.id,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export * from "./format.js";
 export * from "./limits.js";
 export * from "./interaction.js";
 export * from "./fuzzy-search.js";
+export * from "./fuzzy-worker-protocol.js";
+export * from "./fuzzy-worker-client.js";
 export * from "./search-reveal.js";
 export * from "./adapters/docx-images.js";
 export * from "./render-scheduler.js";

package/dist/index.js

@@ -6,6 +6,8 @@ export * from "./format.js";
 export * from "./limits.js";
 export * from "./interaction.js";
 export * from "./fuzzy-search.js";
+export * from "./fuzzy-worker-protocol.js";
+export * from "./fuzzy-worker-client.js";
 export * from "./search-reveal.js";
 export * from "./adapters/docx-images.js";
 export * from "./render-scheduler.js";

package/dist/viewer.js

@@ -3,6 +3,7 @@ import { detectFormat } from "./detect.js";
 import { abortError, normalizeError, ViewerError } from "./errors.js";
 import { cellRangeToTsv, cellRangesToTsv, findNormalizedMatches, normalizeCellRange, } from "./interaction.js";
 import { findFuzzyPageMatches, nearestMatchIndex, pagesNearestFirst, resolveFuzzySearchOptions, } from "./fuzzy-search.js";
+import { FuzzyWorkerClient } from "./fuzzy-worker-client.js";
 import { enforceContainerLimits, resolveLimits } from "./limits.js";
 import { loadDocumentSource } from "./source.js";
 import { AdaptiveViewport } from "./viewport.js";
@@ -31,6 +32,12 @@ export class DocumentViewer {
     #activeSearch;
     #selection = null;
     #searchResult = null;
+    /** Off-thread fuzzy matcher holding the current document's index. */
+    #fuzzyWorker;
+    /** Which pages/options the worker's index was built from; rebuilt on change. */
+    #fuzzyIndexKey;
+    /** Set once the worker failed to start, so the main thread takes over for good. */
+    #fuzzyWorkerUnavailable = false;
     #generation = 0;
     #searchGeneration = 0;
     #viewEventScheduled = false;
@@ -411,26 +418,37 @@ export class DocumentViewer {
                 matches.push(...findNormalizedMatches(text, cleanQuery, pageIndex, caseSensitive));
             }
             if (matches.length === 0 && fuzzy) {
-                // The page texts are already in memory, so the fallback is CPU only.
-                // Pages are compared nearest to the hint first, a batch at a time,
-                // and the scan stops at the first batch that holds the passage; a
-                // yield between batches keeps a long document from freezing the UI.
                 // With a hint the passage sits near it, so only that neighbourhood is
                 // worth the fuzzy cost; without one every page is a candidate.
                 const order = pagesNearestFirst(firstPage, lastPage, nearPage).slice(0, nearPage === undefined ? undefined : fuzzy.pageWindow);
-                for (let offset = 0; offset < order.length && matches.length === 0; offset += fuzzy.pagesPerBatch) {
-                    if (offset > 0)
-                        await yieldToEventLoop();
-                    if (controller.signal.aborted)
-                        throw abortError();
-                    const batch = order
-                        .slice(offset, offset + fuzzy.pagesPerBatch)
-                        .map((pageIndex) => ({
-                        pageIndex,
-                        text: texts.get(pageIndex) ?? "",
-                    }));
-                    matches.push(...findFuzzyPageMatches(batch, cleanQuery, fuzzy, caseSensitive));
-                }
+                const pattern = cleanQuery.slice(0, fuzzy.maxQueryLength);
+                const pages = [];
+                for (const [pageIndex, text] of texts)
+                    pages.push({ pageIndex, text });
+                const offThread = fuzzy.worker
+                    ? await this.#searchFuzzyInWorker(pages, pattern, order, fuzzy, caseSensitive, controller.signal)
+                    : undefined;
+                if (offThread)
+                    matches.push(...offThread);
+                else
+                    for (let offset = 0; offset < order.length && matches.length === 0; offset += fuzzy.pagesPerBatch) {
+                        // The page texts are already in memory, so the fallback is CPU
+                        // only. Pages are compared nearest to the hint first, a batch at
+                        // a time, and the scan stops at the first batch that holds the
+                        // passage; a yield between batches keeps a long document from
+                        // freezing the UI.
+                        if (offset > 0)
+                            await yieldToEventLoop();
+                        if (controller.signal.aborted)
+                            throw abortError();
+                        const batch = order
+                            .slice(offset, offset + fuzzy.pagesPerBatch)
+                            .map((pageIndex) => ({
+                            pageIndex,
+                            text: texts.get(pageIndex) ?? "",
+                        }));
+                        matches.push(...findFuzzyPageMatches(batch, pattern, fuzzy, caseSensitive));
+                    }
                 if (matches.length > 0)
                     strategy = "fuzzy";
             }
@@ -454,6 +472,56 @@ export class DocumentViewer {
                 this.#activeSearch = undefined;
         }
     }
+    /**
+     * Fuzzy scan in the worker. The document's pages are indexed once per
+     * (range, options) and reused by every search until the document closes;
+     * `undefined` hands the scan back to the main thread when the worker is
+     * unavailable or failed, so a missing worker asset degrades to slowness,
+     * never to a lost match.
+     */
+    async #searchFuzzyInWorker(pages, pattern, pageIndices, fuzzy, caseSensitive, signal) {
+        if (this.#fuzzyWorkerUnavailable)
+            return undefined;
+        try {
+            this.#fuzzyWorker ??= FuzzyWorkerClient.create(this.#fuzzyWorkerUrl());
+            if (!this.#fuzzyWorker) {
+                this.#fuzzyWorkerUnavailable = true;
+                return undefined;
+            }
+            const key = `${pages.map((page) => page.pageIndex).join(",")}|${fuzzy.threshold}|${fuzzy.maxPageTextLength}|${caseSensitive}`;
+            if (this.#fuzzyIndexKey !== key) {
+                this.#fuzzyIndexKey = undefined;
+                await this.#fuzzyWorker.index(pages, {
+                    threshold: fuzzy.threshold,
+                    maxPageTextLength: fuzzy.maxPageTextLength,
+                    caseSensitive,
+                });
+                this.#fuzzyIndexKey = key;
+            }
+            const matches = await this.#fuzzyWorker.search(pattern, fuzzy.maxScore, pageIndices);
+            if (signal.aborted)
+                throw abortError();
+            return matches;
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            this.#runtime.logger?.warn?.("Fuzzy search worker unavailable; matching on the main thread", { message: error instanceof Error ? error.message : String(error) });
+            this.#dropFuzzyWorker();
+            this.#fuzzyWorkerUnavailable = true;
+            return undefined;
+        }
+    }
+    #fuzzyWorkerUrl() {
+        return this.#runtime.assetBaseUrl
+            ? new URL("workers/fuzzy-search-worker.js", this.#runtime.assetBaseUrl)
+            : new URL("./workers/fuzzy-search-worker.js", import.meta.url);
+    }
+    #dropFuzzyWorker() {
+        this.#fuzzyWorker?.terminate();
+        this.#fuzzyWorker = undefined;
+        this.#fuzzyIndexKey = undefined;
+    }
     searchNext() {
         return this.#moveSearch(1);
     }
@@ -721,6 +789,7 @@ export class DocumentViewer {
         this.#activeSearch?.abort();
         this.#activeSearch = undefined;
         this.#searchResult = null;
+        this.#dropFuzzyWorker();
         this.#selection = null;
         this.#textMaps.clear();
         this.#textMapBytes = 0;