web-doc 0.4.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/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/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/contracts.d.ts

@@ -236,16 +236,34 @@ export interface FuzzySearchOptions {
      * partly survives on a page, such as a citation that spans a page break.
      */
     readonly maxScore?: number;
-    /** Query characters considered. Default `2000`. */
+    /**
+     * 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 `4`.
+     * 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;
+    /**
+     * 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

@@ -13,6 +13,8 @@ export interface ResolvedFuzzySearchOptions {
     readonly maxQueryLength: number;
     readonly maxPageTextLength: number;
     readonly pagesPerBatch: number;
+    readonly pageWindow: number;
+    readonly worker: boolean;
 }
 export declare const DEFAULT_FUZZY_SEARCH_OPTIONS: ResolvedFuzzySearchOptions;
 /**
@@ -27,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,10 +1,14 @@
-import Fuse from "fuse.js";
+import Fuse, {} from "fuse.js";
 export const DEFAULT_FUZZY_SEARCH_OPTIONS = Object.freeze({
     threshold: 0.3,
     maxScore: 0.4,
-    maxQueryLength: 2000,
+    // 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: 4,
+    pagesPerBatch: 2,
+    pageWindow: 12,
+    worker: true,
 });
 /**
  * Layer fuzzy settings in precedence order (viewer defaults first, then the
@@ -29,24 +33,15 @@ export function resolveFuzzySearchOptions(...layers) {
             maxQueryLength: positiveInteger(layer.maxQueryLength, resolved.maxQueryLength),
             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,
@@ -57,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,10 @@ 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";
 export * from "./i18n.js";
 export * from "./font-manifest.js";

package/dist/index.js

@@ -6,6 +6,10 @@ 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";
 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);
+}