web-doc 0.3.0 → 0.5.0

package/README.md

@@ -9,7 +9,8 @@
 
 > web-doc is a fork of [Zrimo](https://github.com/bnku/zrimo) maintained at
 > [leonidkuznetsov18/web-doc](https://github.com/leonidkuznetsov18/web-doc).
-> It adds page-scoped search (`SearchOptions.pageRange`) and is released
+> It adds page-scoped search (`SearchOptions.pageRange`), an approximate page
+> hint with a fuzzy fallback (`SearchOptions.nearPage` / `fuzzy`) and is released
 > independently; the runtime API, CSS hooks (`.zrimo-ui`, `--zrimo-*`) and
 > asset layout are the same as upstream's `@zrimo/viewer`.
 

package/dist/adapters/bitmap.d.ts

@@ -7,3 +7,12 @@ export declare function drawEncodedImage(data: Uint8Array, mimeType: string, tar
     width: number;
     height: number;
 }>;
+/**
+ * Decode an encoded image only to read its natural size, in CSS pixels at
+ * zoom 1. Uses the same decoder as {@link drawEncodedImage}, so EXIF
+ * orientation is applied and the result matches what a render will draw.
+ */
+export declare function measureEncodedImage(data: Uint8Array, mimeType: string): Promise<{
+    width: number;
+    height: number;
+}>;

package/dist/adapters/bitmap.js

@@ -27,6 +27,20 @@ export async function drawEncodedImage(data, mimeType, target, options) {
         decoded.close();
     }
 }
+/**
+ * Decode an encoded image only to read its natural size, in CSS pixels at
+ * zoom 1. Uses the same decoder as {@link drawEncodedImage}, so EXIF
+ * orientation is applied and the result matches what a render will draw.
+ */
+export async function measureEncodedImage(data, mimeType) {
+    const decoded = await decodeImage(new Blob([data.slice()], { type: mimeType }));
+    try {
+        return { width: decoded.width, height: decoded.height };
+    }
+    finally {
+        decoded.close();
+    }
+}
 async function decodeImage(blob) {
     if (typeof createImageBitmap === "function") {
         const bitmap = await createImageBitmap(blob, {

package/dist/adapters/docx-images.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Word draws an inline picture at its declared extent even when that is wider
+ * than the text area, so a generated document that embeds a 21-inch chart on
+ * a 6.5-inch column shows a clipped picture. A viewer has no margin to spill
+ * into, so before the page layout runs the oversized inline pictures are
+ * scaled down to fit the section's content box, aspect ratio preserved.
+ * Anchored (floating) pictures keep their geometry: their position is part of
+ * the author's layout.
+ */
+export interface DocxSectionGeometry {
+    readonly pageWidth: number;
+    readonly pageHeight: number;
+    readonly marginLeft: number;
+    readonly marginRight: number;
+    readonly marginTop: number;
+    readonly marginBottom: number;
+}
+export interface DocxModelLike {
+    readonly section: DocxSectionGeometry;
+    readonly body: readonly unknown[];
+}
+/**
+ * Shrink every inline picture that would not fit its section's content box.
+ * Mutates the model in place and returns how many pictures were scaled.
+ */
+export declare function fitInlineImagesToPage(model: DocxModelLike): number;

package/dist/adapters/docx-images.js

@@ -0,0 +1,74 @@
+/**
+ * Shrink every inline picture that would not fit its section's content box.
+ * Mutates the model in place and returns how many pictures were scaled.
+ */
+export function fitInlineImagesToPage(model) {
+    let scaled = 0;
+    // A `<w:sectPr>` closes the section that ENDS at it, so the geometry for a
+    // run of body elements is only known once the break after them is reached.
+    let pending = [];
+    const flush = (geometry) => {
+        for (const element of pending)
+            scaled += fitElement(element, geometry);
+        pending = [];
+    };
+    for (const element of model.body) {
+        if (isSectionBreak(element)) {
+            flush(element.geom ?? model.section);
+            continue;
+        }
+        pending.push(element);
+    }
+    flush(model.section);
+    return scaled;
+}
+function fitElement(element, geometry) {
+    if (isParagraph(element)) {
+        let scaled = 0;
+        for (const run of element.runs ?? [])
+            if (isInlineImage(run) && fitImage(run, geometry))
+                scaled += 1;
+        return scaled;
+    }
+    if (isTable(element)) {
+        let scaled = 0;
+        for (const row of element.rows ?? [])
+            for (const cell of row.cells ?? [])
+                for (const child of cell.content ?? [])
+                    scaled += fitElement(child, geometry);
+        return scaled;
+    }
+    return 0;
+}
+function fitImage(image, geometry) {
+    const contentWidth = geometry.pageWidth - geometry.marginLeft - geometry.marginRight;
+    const contentHeight = geometry.pageHeight - geometry.marginTop - geometry.marginBottom;
+    if (!(contentWidth > 0 && contentHeight > 0) ||
+        !(image.widthPt > 0 && image.heightPt > 0))
+        return false;
+    const scale = Math.min(1, contentWidth / image.widthPt, contentHeight / image.heightPt);
+    if (scale >= 1)
+        return false;
+    image.widthPt *= scale;
+    image.heightPt *= scale;
+    return true;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isParagraph(value) {
+    return isRecord(value) && value.type === "paragraph";
+}
+function isTable(value) {
+    return isRecord(value) && value.type === "table";
+}
+function isSectionBreak(value) {
+    return isRecord(value) && value.type === "sectionBreak";
+}
+function isInlineImage(value) {
+    return (isRecord(value) &&
+        value.type === "image" &&
+        value.anchor !== true &&
+        typeof value.widthPt === "number" &&
+        typeof value.heightPt === "number");
+}

package/dist/adapters/image.d.ts

@@ -1,9 +1,11 @@
-import type { AdapterOpenContext, DocumentAdapter, DocumentInfo, RenderViewport, ViewerWarning } from "../contracts.js";
+import type { AdapterOpenContext, DocumentAdapter, DocumentInfo, PageSize, RenderViewport, ViewerWarning } from "../contracts.js";
 type NativeImageFormat = "png" | "jpeg" | "gif" | "webp" | "bmp";
 interface NativeHandle {
     readonly kind: "native";
     readonly format: NativeImageFormat;
     readonly data: Uint8Array;
+    /** Natural size when the browser could decode the image at open time. */
+    readonly size: PageSize | undefined;
     readonly warnings: readonly ViewerWarning[];
 }
 interface TiffHandle {

package/dist/adapters/image.js

@@ -1,5 +1,5 @@
 import { abortError, ViewerError } from "../errors.js";
-import { drawEncodedImage } from "./bitmap.js";
+import { drawEncodedImage, measureEncodedImage } from "./bitmap.js";
 export class ImageDocumentAdapter {
     id = "image";
     formats = ["png", "jpeg", "gif", "webp", "bmp", "tiff"];
@@ -35,10 +35,14 @@ export class ImageDocumentAdapter {
         }
         const format = context.format;
         const animated = isAnimated(data, format);
+        const size = await measureNativeImage(data, format);
+        if (context.signal.aborted)
+            throw abortError();
         return {
             kind: "native",
             format,
             data,
+            size,
             warnings: animated
                 ? [
                     {
@@ -51,10 +55,12 @@ export class ImageDocumentAdapter {
         };
     }
     async getInfo(handle) {
+        const pageSizes = pageSizesOf(handle);
         return {
             format: handle.format,
             unit: "image",
             pageCount: handle.kind === "tiff" ? handle.backend.pages.length : 1,
+            ...(pageSizes ? { pageSizes } : {}),
             warnings: handle.warnings,
         };
     }
@@ -180,6 +186,30 @@ function requestWorker(worker, payload, transfer, signal, timeoutMs = 30_000) {
         worker.postMessage(payload, transfer);
     });
 }
+/**
+ * Natural page geometry for the viewport layout and fit modes. Without it the
+ * viewport falls back to a letter-sized page, so fit-to-width scales a photo
+ * against a size it does not have and the bitmap overflows its slot.
+ */
+function pageSizesOf(handle) {
+    if (handle.kind === "tiff")
+        return handle.backend.pages.map(({ width, height }) => ({ width, height }));
+    return handle.size ? [handle.size] : undefined;
+}
+/**
+ * Read the natural size once at open time. A decode failure is not fatal here:
+ * the render path reports it with its own error, and the viewport keeps its
+ * fallback geometry until then.
+ */
+async function measureNativeImage(data, format) {
+    try {
+        const { width, height } = await measureEncodedImage(data, mimeType(format));
+        return width > 0 && height > 0 ? { width, height } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function mimeType(format) {
     return format === "jpeg" ? "image/jpeg" : `image/${format}`;
 }

package/dist/adapters/office.d.ts

@@ -1,4 +1,5 @@
 import type { AdapterOpenContext, DocumentAdapter, DocumentFormat, DocumentInfo, HyperlinkTarget, RenderViewport, SpreadsheetSheetInfo, TextRun, ViewerWarning } from "../contracts.js";
+import { type DocxModelLike } from "./docx-images.js";
 declare const LEGACY_FORMATS: readonly ["doc", "xls", "ppt"];
 type LegacyFormat = (typeof LEGACY_FORMATS)[number];
 interface EngineLoadOptions {
@@ -27,6 +28,10 @@ interface DocxRun {
 }
 interface DocxBackend {
     readonly pageCount: number;
+    /** Render mode; the parsed model is only reachable in `main` mode. */
+    readonly mode?: "main" | "worker";
+    /** Parsed document model (main mode). Read lazily by the page layout. */
+    readonly document?: DocxModelLike;
     pageSize(pageIndex: number): {
         widthPt: number;
         heightPt: number;

package/dist/adapters/office.js

@@ -1,4 +1,5 @@
 import { abortError, ViewerError } from "../errors.js";
+import { fitInlineImagesToPage } from "./docx-images.js";
 import { enforceContainerLimits } from "../limits.js";
 const MODERN_FORMATS = [
     "docx",
@@ -325,10 +326,11 @@ export class OfficeDocumentAdapter {
         return convertInWorker(data, format, workerUrl, moduleUrl, context.signal, context.limits.maxOperationMs);
     }
     async #loadDocx(data, options) {
-        if (this.#options.engines?.docx)
-            return this.#options.engines.docx(data, options);
-        const { DocxDocument } = await import("@silurus/ooxml/docx");
-        return DocxDocument.load(data, options);
+        const backend = this.#options.engines?.docx
+            ? await this.#options.engines.docx(data, options)
+            : await (await import("@silurus/ooxml/docx")).DocxDocument.load(data, options);
+        fitDocxInlineImages(backend);
+        return backend;
     }
     async #loadXlsx(data, options) {
         if (this.#options.engines?.xlsx)
@@ -670,3 +672,22 @@ function normalizeOfficeError(error) {
 function textDirection(text) {
     return /[\u0590-\u08ff\ufb1d-\ufefc]/u.test(text) ? "rtl" : "ltr";
 }
+/**
+ * Oversized inline pictures are shrunk to the section's content box before
+ * the engine paginates (the layout is built lazily on first page access).
+ * The model is reachable in `main` mode only; a worker-mode engine keeps
+ * Word's geometry.
+ */
+function fitDocxInlineImages(backend) {
+    if (backend.mode === "worker")
+        return;
+    let model;
+    try {
+        model = backend.document;
+    }
+    catch {
+        return;
+    }
+    if (model)
+        fitInlineImagesToPage(model);
+}

package/dist/adapters/svg.d.ts

@@ -1,6 +1,8 @@
-import type { AdapterOpenContext, DocumentAdapter, DocumentInfo, RenderViewport, ViewerWarning } from "../contracts.js";
+import type { AdapterOpenContext, DocumentAdapter, DocumentInfo, PageSize, RenderViewport, ViewerWarning } from "../contracts.js";
 interface SvgHandle {
     readonly data: Uint8Array;
+    /** Intrinsic size from the root `width`/`height` or `viewBox`, when declared. */
+    readonly size: PageSize | undefined;
     readonly warnings: readonly ViewerWarning[];
 }
 export declare class SvgDocumentAdapter implements DocumentAdapter<SvgHandle> {
@@ -13,5 +15,12 @@ export declare class SvgDocumentAdapter implements DocumentAdapter<SvgHandle> {
     close(): void;
 }
 export declare function sanitizeSvg(source: string): string;
+/**
+ * Intrinsic size of the root `<svg>` in CSS pixels at zoom 1: explicit
+ * `width`/`height` win, a `viewBox` stands in for a missing pair, and a
+ * document that declares neither has no natural size (the viewport keeps its
+ * fallback page geometry).
+ */
+export declare function parseSvgSize(source: string): PageSize | undefined;
 export declare function createSvgAdapter(): SvgDocumentAdapter;
 export {};

package/dist/adapters/svg.js

@@ -19,6 +19,7 @@ export class SvgDocumentAdapter {
         const changed = sanitized !== source;
         return {
             data: new TextEncoder().encode(sanitized),
+            size: parseSvgSize(sanitized),
             warnings: changed
                 ? [
                     {
@@ -34,6 +35,7 @@ export class SvgDocumentAdapter {
             format: "svg",
             unit: "image",
             pageCount: 1,
+            ...(handle.size ? { pageSizes: [handle.size] } : {}),
             warnings: handle.warnings,
         };
     }
@@ -93,6 +95,61 @@ export function sanitizeSvg(source) {
     }
     return new XMLSerializer().serializeToString(document.documentElement);
 }
+/** CSS absolute units → CSS pixels; percentages and unknown units are ignored. */
+const SVG_LENGTH_UNITS = {
+    "": 1,
+    px: 1,
+    pt: 96 / 72,
+    pc: 16,
+    in: 96,
+    cm: 96 / 2.54,
+    mm: 96 / 25.4,
+};
+/**
+ * Intrinsic size of the root `<svg>` in CSS pixels at zoom 1: explicit
+ * `width`/`height` win, a `viewBox` stands in for a missing pair, and a
+ * document that declares neither has no natural size (the viewport keeps its
+ * fallback page geometry).
+ */
+export function parseSvgSize(source) {
+    const root = /<svg\b([^>]*)>/i.exec(source);
+    if (!root)
+        return undefined;
+    const width = parseSvgLength(svgAttribute(root[1] ?? "", "width"));
+    const height = parseSvgLength(svgAttribute(root[1] ?? "", "height"));
+    if (width && height)
+        return { width, height };
+    const viewBox = svgAttribute(root[1] ?? "", "viewBox")
+        ?.trim()
+        .split(/[\s,]+/)
+        .map(Number);
+    if (viewBox?.length === 4 &&
+        viewBox.every(Number.isFinite) &&
+        viewBox[2] > 0 &&
+        viewBox[3] > 0) {
+        // One declared side scales the viewBox aspect; none means viewBox units.
+        if (width)
+            return { width, height: (width * viewBox[3]) / viewBox[2] };
+        if (height)
+            return { width: (height * viewBox[2]) / viewBox[3], height };
+        return { width: viewBox[2], height: viewBox[3] };
+    }
+    return undefined;
+}
+function svgAttribute(attributes, name) {
+    const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "i").exec(attributes);
+    return match?.[1] ?? match?.[2];
+}
+function parseSvgLength(value) {
+    const match = /^\s*([0-9]*\.?[0-9]+(?:e[+-]?[0-9]+)?)\s*([a-z%]*)\s*$/i.exec(value ?? "");
+    if (!match)
+        return undefined;
+    const factor = SVG_LENGTH_UNITS[match[2].toLowerCase()];
+    if (factor === undefined)
+        return undefined;
+    const length = Number(match[1]) * factor;
+    return Number.isFinite(length) && length > 0 ? length : undefined;
+}
 export function createSvgAdapter() {
     return new SvgDocumentAdapter();
 }

package/dist/contracts.d.ts

@@ -112,6 +112,7 @@ export interface ViewerOptions {
     readonly layout?: "continuous" | "single";
     readonly overscan?: number;
     readonly translations?: Partial<ViewerTranslations>;
+    readonly search?: SearchDefaults;
 }
 export interface ViewerClientOptions {
     readonly fetch?: ViewerFetch;
@@ -216,6 +217,47 @@ export interface ViewerEventMap {
     readonly viewchange: ViewerState;
     readonly searchchange: SearchResult | null;
 }
+/**
+ * Tuning for the fuzzy fallback that runs when the exact search finds
+ * nothing. Matching is delegated to Fuse.js: the query is compared to each
+ * page's text with a bounded edit budget, so spacing, line breaks, list
+ * bullets, table separators and typographic punctuation may differ from the
+ * source, and every hit maps back to the verbatim page text.
+ */
+export interface FuzzySearchOptions {
+    /**
+     * Fuse.js `threshold`: the edit budget per 32-character chunk of the query,
+     * `0` exact to `1` anything. Default `0.3`.
+     */
+    readonly threshold?: number;
+    /**
+     * Highest Fuse.js score (`0` perfect, `1` no resemblance) a page may have to
+     * count as a match. Default `0.4`; raise it to accept a passage that only
+     * partly survives on a page, such as a citation that spans a page break.
+     */
+    readonly maxScore?: number;
+    /**
+     * Query characters considered. The matcher's cost grows with the query and
+     * a passage is identified well before its end, so the default `600` keeps
+     * a page under about 100 ms; the highlight covers the matched prefix.
+     */
+    readonly maxQueryLength?: number;
+    /** Characters of each page's text considered. Default `20000`. */
+    readonly maxPageTextLength?: number;
+    /**
+     * Pages compared per batch. The scan proceeds nearest to `nearPage` first
+     * and stops after the first batch with a match, yielding to the event loop
+     * between batches. Default `2`.
+     */
+    readonly pagesPerBatch?: number;
+    /**
+     * With `nearPage`, how many pages nearest to the hint the fallback scans
+     * before giving up; the passage a hint points at sits within a few pages
+     * of it, and the rest of a long document is not worth the cost. Without a
+     * hint every page in range is scanned. Default `12`.
+     */
+    readonly pageWindow?: number;
+}
 export interface SearchOptions {
     readonly caseSensitive?: boolean;
     /**
@@ -225,6 +267,24 @@ export interface SearchOptions {
      * is rejected.
      */
     readonly pageRange?: readonly [number, number];
+    /**
+     * Approximate 0-based page the passage is expected on, for callers whose
+     * page numbers come from another pagination (a citation produced from a
+     * server-side render of the same file). Clamped to the document. The
+     * result's `activeIndex` becomes the match closest to it, and the fuzzy
+     * fallback scans pages nearest to it first.
+     */
+    readonly nearPage?: number;
+    /**
+     * Fall back to Fuse.js fuzzy matching when the exact search finds nothing.
+     * `true` uses the viewer's `search.fuzzy` defaults; an object enables it
+     * and overrides them; `false` disables it for this call.
+     */
+    readonly fuzzy?: boolean | FuzzySearchOptions;
+}
+/** Per-viewer defaults applied to every `search()` call. */
+export interface SearchDefaults {
+    readonly fuzzy?: boolean | FuzzySearchOptions;
 }
 export interface SearchMatch {
     readonly pageIndex: number;
@@ -232,10 +292,14 @@ export interface SearchMatch {
     readonly end: number;
     readonly text: string;
 }
+/** How the matches of a result were found. */
+export type SearchStrategy = "exact" | "fuzzy";
 export interface SearchResult {
     readonly query: string;
     readonly matches: readonly SearchMatch[];
     readonly activeIndex: number;
+    /** Present when the result has matches. */
+    readonly strategy?: SearchStrategy;
 }
 export interface HeadlessRenderOptions {
     readonly zoom?: number;

package/dist/fuzzy-search.d.ts

@@ -0,0 +1,39 @@
+import type { FuzzySearchOptions, SearchMatch } from "./contracts.js";
+/**
+ * Fuzzy matching is delegated to Fuse.js (Bitap with a bounded edit budget per
+ * 32-character chunk). It bridges the gaps NFKC + case folding leave open when
+ * a query was not copied verbatim from the document: AI-generated citations
+ * and OCR'd passages differ from the source in spacing, line breaks, list
+ * bullets, table separators and typographic punctuation. Every hit maps back
+ * to original UTF-16 offsets, so the viewport highlights the verbatim text.
+ */
+export interface ResolvedFuzzySearchOptions {
+    readonly threshold: number;
+    readonly maxScore: number;
+    readonly maxQueryLength: number;
+    readonly maxPageTextLength: number;
+    readonly pagesPerBatch: number;
+    readonly pageWindow: number;
+}
+export declare const DEFAULT_FUZZY_SEARCH_OPTIONS: ResolvedFuzzySearchOptions;
+/**
+ * Layer fuzzy settings in precedence order (viewer defaults first, then the
+ * per-call option). `true` enables the defaults, an object enables and
+ * overrides them, `false` disables, `undefined` leaves the previous layer in
+ * place. Returns `undefined` when fuzzy matching ends up disabled.
+ */
+export declare function resolveFuzzySearchOptions(...layers: readonly (boolean | FuzzySearchOptions | undefined)[]): ResolvedFuzzySearchOptions | undefined;
+export interface FuzzyPageText {
+    readonly pageIndex: number;
+    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.
+ */
+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. */
+export declare function pagesNearestFirst(first: number, last: number, nearPage: number | undefined): number[];
+/** Index of the match closest to `nearPage`; the first match when there is no hint. */
+export declare function nearestMatchIndex(matches: readonly SearchMatch[], nearPage: number | undefined): number;

package/dist/fuzzy-search.js

@@ -0,0 +1,118 @@
+import Fuse from "fuse.js";
+export const DEFAULT_FUZZY_SEARCH_OPTIONS = Object.freeze({
+    threshold: 0.3,
+    maxScore: 0.4,
+    // Bitap cost grows with the query; 600 characters still identifies a
+    // passage while keeping a page under ~100 ms on a laptop.
+    maxQueryLength: 600,
+    maxPageTextLength: 20_000,
+    pagesPerBatch: 2,
+    pageWindow: 12,
+});
+/**
+ * Layer fuzzy settings in precedence order (viewer defaults first, then the
+ * per-call option). `true` enables the defaults, an object enables and
+ * overrides them, `false` disables, `undefined` leaves the previous layer in
+ * place. Returns `undefined` when fuzzy matching ends up disabled.
+ */
+export function resolveFuzzySearchOptions(...layers) {
+    let enabled = false;
+    let resolved = DEFAULT_FUZZY_SEARCH_OPTIONS;
+    for (const layer of layers) {
+        if (layer === undefined)
+            continue;
+        if (typeof layer === "boolean") {
+            enabled = layer;
+            continue;
+        }
+        enabled = true;
+        resolved = {
+            threshold: unitInterval(layer.threshold, resolved.threshold),
+            maxScore: unitInterval(layer.maxScore, resolved.maxScore),
+            maxQueryLength: positiveInteger(layer.maxQueryLength, resolved.maxQueryLength),
+            maxPageTextLength: positiveInteger(layer.maxPageTextLength, resolved.maxPageTextLength),
+            pagesPerBatch: positiveInteger(layer.pagesPerBatch, resolved.pagesPerBatch),
+            pageWindow: positiveInteger(layer.pageWindow, resolved.pageWindow),
+        };
+    }
+    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, {
+        keys: ["text"],
+        isCaseSensitive: caseSensitive,
+        ignoreDiacritics: false,
+        includeMatches: true,
+        includeScore: true,
+        // A citation can sit anywhere on the page; Fuse's location bias would
+        // otherwise penalize matches far from the start of the text.
+        ignoreLocation: true,
+        // Long page text must not dilute the score of a match inside it.
+        ignoreFieldNorm: true,
+        threshold: options.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);
+        }
+        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);
+}
+/** Page indices of `[first, last]` ordered by distance from `nearPage`, ties earlier-first. */
+export function pagesNearestFirst(first, last, nearPage) {
+    const pages = Array.from({ length: last - first + 1 }, (_, i) => first + i);
+    if (nearPage === undefined)
+        return pages;
+    return pages.sort((a, b) => Math.abs(a - nearPage) - Math.abs(b - nearPage) || a - b);
+}
+/** Index of the match closest to `nearPage`; the first match when there is no hint. */
+export function nearestMatchIndex(matches, nearPage) {
+    if (matches.length === 0)
+        return -1;
+    if (nearPage === undefined)
+        return 0;
+    let best = 0;
+    for (let index = 1; index < matches.length; index += 1)
+        if (Math.abs(matches[index].pageIndex - nearPage) <
+            Math.abs(matches[best].pageIndex - nearPage))
+            best = index;
+    return best;
+}
+function unitInterval(value, fallback) {
+    return value !== undefined &&
+        Number.isFinite(value) &&
+        value >= 0 &&
+        value <= 1
+        ? value
+        : fallback;
+}
+function positiveInteger(value, fallback) {
+    return value !== undefined && Number.isInteger(value) && value > 0
+        ? value
+        : fallback;
+}

package/dist/index.d.ts

@@ -5,6 +5,9 @@ export * from "./errors.js";
 export * from "./format.js";
 export * from "./limits.js";
 export * from "./interaction.js";
+export * from "./fuzzy-search.js";
+export * from "./search-reveal.js";
+export * from "./adapters/docx-images.js";
 export * from "./render-scheduler.js";
 export * from "./i18n.js";
 export * from "./font-manifest.js";

package/dist/index.js

@@ -5,6 +5,9 @@ export * from "./errors.js";
 export * from "./format.js";
 export * from "./limits.js";
 export * from "./interaction.js";
+export * from "./fuzzy-search.js";
+export * from "./search-reveal.js";
+export * from "./adapters/docx-images.js";
 export * from "./render-scheduler.js";
 export * from "./i18n.js";
 export * from "./font-manifest.js";

package/dist/search-reveal.d.ts

@@ -0,0 +1,21 @@
+import type { SearchMatch, TextRun } from "./contracts.js";
+/**
+ * Vertical position of a match inside its page, in the coordinate units of
+ * the page's text layer: the `y` of the first run the match overlaps.
+ * Offsets follow the same convention as the highlight layers (a run's
+ * explicit `logicalStart`/`logicalEnd`, else the running text length), so
+ * the position agrees with where the highlight is painted. `undefined` when
+ * no run overlaps the match.
+ */
+export declare function matchTopInPage(runs: readonly TextRun[], match: SearchMatch): number | undefined;
+/**
+ * Scroll offset that places a match about a third of the way down the
+ * viewport — far enough from the top edge to read the line before it, never
+ * above the page's own top so a match near the top of a page still shows the
+ * page head. `matchTop` is the match's offset from the page top in CSS px.
+ */
+export declare function revealScrollTop(options: {
+    readonly pageTop: number;
+    readonly matchTop: number;
+    readonly viewportHeight: number;
+}): number;

package/dist/search-reveal.js

@@ -0,0 +1,29 @@
+/**
+ * Vertical position of a match inside its page, in the coordinate units of
+ * the page's text layer: the `y` of the first run the match overlaps.
+ * Offsets follow the same convention as the highlight layers (a run's
+ * explicit `logicalStart`/`logicalEnd`, else the running text length), so
+ * the position agrees with where the highlight is painted. `undefined` when
+ * no run overlaps the match.
+ */
+export function matchTopInPage(runs, match) {
+    let offset = 0;
+    for (const run of runs) {
+        const start = run.logicalStart ?? offset;
+        const end = run.logicalEnd ?? start + run.text.length;
+        offset = end;
+        if (match.start < end && match.end > start)
+            return run.y;
+    }
+    return undefined;
+}
+/**
+ * Scroll offset that places a match about a third of the way down the
+ * viewport — far enough from the top edge to read the line before it, never
+ * above the page's own top so a match near the top of a page still shows the
+ * page head. `matchTop` is the match's offset from the page top in CSS px.
+ */
+export function revealScrollTop(options) {
+    const lead = Math.max(0, options.viewportHeight) / 3;
+    return Math.max(options.pageTop, options.pageTop + options.matchTop - lead);
+}

package/dist/spreadsheet-viewport.d.ts

@@ -24,6 +24,8 @@ export declare class SpreadsheetViewport {
     setDocument(info: DocumentInfo | undefined): void;
     update(): void;
     panBy(deltaX: number, deltaY: number): void;
+    /** Sheet matches are cell-addressed; the sheet viewport scrolls per cell already. */
+    revealMatch(): Promise<void>;
     goToPage(pageIndex: number): void;
     fitWidth(): number;
     fitPage(): number;

package/dist/spreadsheet-viewport.js

@@ -241,6 +241,8 @@ export class SpreadsheetViewport {
         this.#reportPan();
         this.schedule();
     }
+    /** Sheet matches are cell-addressed; the sheet viewport scrolls per cell already. */
+    async revealMatch() { }
     goToPage(pageIndex) {
         if (pageIndex === this.#sheetIndex)
             return;

package/dist/viewer.js

@@ -2,6 +2,7 @@ import { linkedAbortController } from "./abort.js";
 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 { enforceContainerLimits, resolveLimits } from "./limits.js";
 import { loadDocumentSource } from "./source.js";
 import { AdaptiveViewport } from "./viewport.js";
@@ -386,6 +387,9 @@ export class DocumentViewer {
         // Validated before the in-flight search is cancelled so a rejected range
         // leaves the current result and highlights untouched.
         const [firstPage, lastPage] = resolveSearchPageRange(info.pageCount, options.pageRange);
+        const nearPage = resolveNearPage(firstPage, lastPage, options.nearPage);
+        const fuzzy = resolveFuzzySearchOptions(this.#options.search?.fuzzy, options.fuzzy);
+        const caseSensitive = options.caseSensitive ?? false;
         this.#activeSearch?.abort();
         const controller = new AbortController();
         this.#activeSearch = controller;
@@ -396,23 +400,51 @@ export class DocumentViewer {
             return immutableSearchResult({ query, matches: [], activeIndex: -1 });
         }
         const matches = [];
+        let strategy = "exact";
         try {
+            const texts = new Map();
             for (let pageIndex = firstPage; pageIndex <= lastPage; pageIndex += 1) {
                 if (controller.signal.aborted)
                     throw abortError();
                 const text = await this.getPageText(pageIndex, controller.signal);
-                matches.push(...findNormalizedMatches(text, cleanQuery, pageIndex, options.caseSensitive ?? false));
+                texts.set(pageIndex, text);
+                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));
+                }
+                if (matches.length > 0)
+                    strategy = "fuzzy";
             }
             if (generation !== this.#searchGeneration)
                 throw abortError();
             const result = immutableSearchResult({
                 query,
                 matches,
-                activeIndex: matches.length > 0 ? 0 : -1,
+                activeIndex: nearestMatchIndex(matches, nearPage),
+                ...(matches.length > 0 ? { strategy } : {}),
             });
             this.#searchResult = result;
             if (result.activeIndex >= 0)
-                this.#goToPage(result.matches[result.activeIndex].pageIndex, true);
+                this.#revealSearchMatch(result.matches[result.activeIndex]);
             this.#emit("searchchange", result);
             this.#viewport?.update();
             return result;
@@ -653,11 +685,16 @@ export class DocumentViewer {
             current.matches.length;
         const result = immutableSearchResult({ ...current, activeIndex });
         this.#searchResult = result;
-        this.#goToPage(result.matches[activeIndex].pageIndex, true);
+        this.#revealSearchMatch(result.matches[activeIndex]);
         this.#emit("searchchange", result);
         this.#viewport?.update();
         return result;
     }
+    /** Land on the match's page, then bring the match itself into view. */
+    #revealSearchMatch(match) {
+        this.#goToPage(match.pageIndex, true);
+        void this.#viewport?.revealMatch(match);
+    }
     #goToPage(pageIndex, scrollViewport) {
         this.#assertAlive();
         const upperBound = Math.max(0, this.#state.pageCount - 1);
@@ -783,6 +820,19 @@ function resolveSearchPageRange(pageCount, pageRange) {
     assertPageIndex(last, pageCount);
     return first <= last ? [first, last] : [last, first];
 }
+/**
+ * Clamp the approximate page hint into the scanned window. A hint that comes
+ * from another pagination of the same file is allowed to overshoot; rejecting
+ * it would defeat its purpose.
+ */
+function resolveNearPage(firstPage, lastPage, nearPage) {
+    if (nearPage === undefined || !Number.isFinite(nearPage))
+        return undefined;
+    return Math.min(lastPage, Math.max(firstPage, Math.trunc(nearPage)));
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
 function assertPageIndex(pageIndex, pageCount) {
     if (!Number.isInteger(pageIndex) || pageIndex < 0 || pageIndex >= pageCount)
         throw new ViewerError("render-failed", "Page index is out of range", {

package/dist/viewport.d.ts

@@ -18,6 +18,7 @@ interface ViewportStrategy {
     update(): void;
     panBy(deltaX: number, deltaY: number): void;
     goToPage(pageIndex: number): void;
+    revealMatch(match: SearchMatch): Promise<void>;
     fitWidth(): number;
     fitPage(): number;
     destroy(): void;
@@ -32,6 +33,7 @@ export declare class AdaptiveViewport implements ViewportStrategy {
     update(): void;
     panBy(deltaX: number, deltaY: number): void;
     goToPage(pageIndex: number): void;
+    revealMatch(match: SearchMatch): Promise<void>;
     fitWidth(): number;
     fitPage(): number;
     destroy(): void;
@@ -46,6 +48,13 @@ export declare class ViewerViewport {
     update(): void;
     panBy(deltaX: number, deltaY: number): void;
     goToPage(pageIndex: number): void;
+    /**
+     * Scroll so the match itself is in view, not just its page: a page can be
+     * taller than the viewport, and a search that only lands on the page top
+     * leaves a match further down invisible until the reader scrolls. Resolves
+     * once the text runs are known; a navigation that happened meanwhile wins.
+     */
+    revealMatch(match: SearchMatch): Promise<void>;
     fitWidth(): number;
     fitPage(): number;
     schedule(): void;

package/dist/viewport.js

@@ -1,8 +1,11 @@
+import { matchTopInPage, revealScrollTop } from "./search-reveal.js";
 import { snapGraphemeOffset } from "./interaction.js";
 import { SpreadsheetViewport } from "./spreadsheet-viewport.js";
 const BASE_WIDTH = 816;
 const BASE_HEIGHT = 1056;
 const PAGE_GAP = 24;
+/** Page slots sit this far inside the spacer (top and left). */
+const SLOT_INSET = 12;
 export class AdaptiveViewport {
     #container;
     #host;
@@ -36,6 +39,9 @@ export class AdaptiveViewport {
     goToPage(pageIndex) {
         this.#strategy.goToPage(pageIndex);
     }
+    revealMatch(match) {
+        return this.#strategy.revealMatch(match);
+    }
     fitWidth() {
         return this.#strategy.fitWidth();
     }
@@ -154,6 +160,36 @@ export class ViewerViewport {
         }
         this.schedule();
     }
+    /**
+     * Scroll so the match itself is in view, not just its page: a page can be
+     * taller than the viewport, and a search that only lands on the page top
+     * leaves a match further down invisible until the reader scrolls. Resolves
+     * once the text runs are known; a navigation that happened meanwhile wins.
+     */
+    async revealMatch(match) {
+        if (this.#layout !== "continuous" || !this.#info)
+            return;
+        let runs;
+        try {
+            runs = await this.#host.getTextRuns(match.pageIndex);
+        }
+        catch {
+            return;
+        }
+        if (this.#destroyed || this.#host.state.pageIndex !== match.pageIndex)
+            return;
+        const top = matchTopInPage(runs, match);
+        if (top === undefined)
+            return;
+        const zoom = this.#host.state.zoom;
+        const metrics = pageMetrics(this.#info, zoom);
+        this.#root.scrollTop = revealScrollTop({
+            pageTop: metrics.offsets[match.pageIndex] ?? 0,
+            matchTop: SLOT_INSET + top * zoom,
+            viewportHeight: this.#root.clientHeight,
+        });
+        this.schedule();
+    }
     fitWidth() {
         const size = naturalPageSize(this.#info, this.#host.state.pageIndex);
         return Math.max(0.1, Math.min(8, (this.#root.clientWidth - 24) / size.width));
@@ -217,7 +253,9 @@ export class ViewerViewport {
             const slot = this.#slots.get(pageIndex) ?? this.#createSlot(pageIndex);
             const width = metrics.widths[pageIndex] ?? BASE_WIDTH * state.zoom;
             const height = metrics.heights[pageIndex] ?? BASE_HEIGHT * state.zoom;
-            const top = this.#layout === "single" ? 12 : (metrics.offsets[pageIndex] ?? 0) + 12;
+            const top = this.#layout === "single"
+                ? SLOT_INSET
+                : (metrics.offsets[pageIndex] ?? 0) + SLOT_INSET;
             const contentWidth = Math.max(this.#root.clientWidth, metrics.maxWidth + 24);
             slot.root.style.top = `${top}px`;
             slot.root.style.left = `${Math.max(12, (contentWidth - width) / 2)}px`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-doc",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "web-doc — embeddable browser-only document viewer with Rust/WASM adapters (a fork of Zrimo)",
   "keywords": [
     "document-viewer",
@@ -69,6 +69,7 @@
   },
   "dependencies": {
     "@silurus/ooxml": "0.72.2",
+    "fuse.js": "7.5.0",
     "pdfjs-dist": "6.2.108"
   }
 }