wolfy-reader 0.1.0

package/dist/search/extract.js

@@ -0,0 +1,401 @@
+/**
+ * Per-section text extraction for search. Decodes a section's bytes and strips its
+ * markup to a single plain string — the **canonical reading text**, the same text
+ * the frame ultimately shows and measures, so a match's captured anchor (quote +
+ * context) exists verbatim in the text `goTo` resolves against.
+ *
+ * Headless by rule: this imports only `src/core` (the shared reading-text policy)
+ * and platform primitives (`TextDecoder`) and never touches `document`/`window`, so
+ * the whole search stack runs under `node:test`. It deliberately does **not** route
+ * through the frame's `Paginator.sectionText()` — that returns only the
+ * currently-paginated section and needs a browser. Search scans every section
+ * without painting it.
+ *
+ * Extraction is a small tag-stripping tokenizer rather than `DOMParser`: `DOMParser`
+ * is a browser primitive with no headless Node global, and search only needs text
+ * content. To line up with the frame it mirrors what the sanitize + resource
+ * pipeline does to a section's text, via the one shared policy in
+ * `src/core/reading-text.ts`:
+ *
+ * - Inline markup contributes no characters (`wo<em>rd</em>` is found as `word`) —
+ *   `textContent` semantics, and unwrapped elements keep their text.
+ * - Elements the sanitizer **discards whole** (form controls, `template`, raw-text
+ *   containers — `DISCARDED_HTML_ELEMENTS` / `DISCARDED_SVG_ELEMENTS`) contribute
+ *   nothing, exactly as their text never reaches the frame.
+ * - An `<img>` contributes what the resource layer will show: nothing when it can
+ *   be served (or is left for the CSP), its `alt` when the frame substitutes alt
+ *   text (`imageReadingText`) — which is why extraction takes the section's
+ *   `resolve` seam.
+ * - Whitespace-only text runs at the top level of the body are dropped, because
+ *   the chunker drops those text nodes before the frame tiles the section text
+ *   (`chunkElement` in `src/layout/chunk.ts`).
+ * - `head`, `script` and `style` content is never reading text (`<style>` survives
+ *   sanitization, but its CSS is source, not prose — searching it would be noise;
+ *   see the known-edges note in docs/domains/search.md).
+ */
+import { DISCARDED_HTML_ELEMENTS, DISCARDED_SVG_ELEMENTS, imageReadingText, } from '../core/reading-text.js';
+import { decodeText } from '../core/text.js';
+/** Decodes section bytes honouring the byte-order marks EPUB allows. */
+export { decodeText as decodeSectionBytes } from '../core/text.js';
+/**
+ * Elements whose content the HTML parser reads as raw text (a `<` in `1<2` inside
+ * `<script>` is not a tag): skipping jumps to the first matching end tag rather
+ * than tracking nesting. All but `style` are also discarded by the sanitizer;
+ * `style` survives into the frame but its text is source, not prose.
+ */
+const RAW_TEXT = new Set([
+    'iframe',
+    'noembed',
+    'noframes',
+    'plaintext',
+    'script',
+    'style',
+    'textarea',
+    'title',
+    'xmp',
+]);
+/** HTML void elements: no content, no end tag, never on the open-element stack. */
+const VOID = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+/**
+ * Block-level tags whose start tag implies `</p>` in HTML parsing. Without this,
+ * the unclosed `<p>` real books ship would keep the stack forever nested and the
+ * top-level whitespace rule would never apply again.
+ */
+const P_CLOSERS = new Set([
+    'address',
+    'article',
+    'aside',
+    'blockquote',
+    'details',
+    'div',
+    'dl',
+    'fieldset',
+    'figcaption',
+    'figure',
+    'footer',
+    'form',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'header',
+    'hgroup',
+    'hr',
+    'main',
+    'menu',
+    'nav',
+    'ol',
+    'p',
+    'pre',
+    'section',
+    'table',
+    'ul',
+]);
+/**
+ * Extracts a section's reading text from its decoded markup — the headless mirror
+ * of what the sanitize + resource pipeline leaves for the frame to show (see the
+ * module comment for the exact rules). `resolve` is the section's own resolver
+ * seam (`Section.resolve`), consulted only to decide whether an `<img>` renders
+ * or falls back to its alt text; omit it and every in-book image degrades to alt,
+ * matching a section that carries no resolver.
+ */
+export function extractText(markup, resolve) {
+    let out = '';
+    let index = 0;
+    /** Open non-void elements. `head` and skipped containers never land here. */
+    const stack = [];
+    let svgDepth = 0;
+    // The chunker drops whitespace-only text nodes at the top level of the body
+    // (they carry no block box), so the frame's tiled text has no inter-paragraph
+    // source whitespace. Mirror it: a whitespace-only run emitted while no element
+    // (or only html/body) is open contributes nothing.
+    const atTopLevel = () => {
+        const top = stack[stack.length - 1];
+        return top === undefined || top === 'html' || top === 'body';
+    };
+    const emit = (text) => {
+        if (text === '')
+            return;
+        if (atTopLevel() && text.trim().length === 0)
+            return;
+        out += text;
+    };
+    const popTo = (name) => {
+        const at = stack.lastIndexOf(name);
+        if (at === -1)
+            return;
+        for (let i = stack.length - 1; i >= at; i -= 1) {
+            if (stack[i] === 'svg')
+                svgDepth -= 1;
+        }
+        stack.length = at;
+    };
+    const length = markup.length;
+    while (index < length) {
+        const lt = markup.indexOf('<', index);
+        if (lt === -1) {
+            emit(decodeEntities(markup.slice(index)));
+            break;
+        }
+        if (lt > index)
+            emit(decodeEntities(markup.slice(index, lt)));
+        // Comment / CDATA / processing instruction / doctype: skip to its close.
+        if (markup.startsWith('<!--', lt)) {
+            const close = markup.indexOf('-->', lt + 4);
+            index = close === -1 ? length : close + 3;
+            continue;
+        }
+        if (markup.startsWith('<![CDATA[', lt)) {
+            const close = markup.indexOf(']]>', lt + 9);
+            emit(markup.slice(lt + 9, close === -1 ? length : close)); // literal text, no entities
+            index = close === -1 ? length : close + 3;
+            continue;
+        }
+        if (markup[lt + 1] === '!' || markup[lt + 1] === '?') {
+            const close = markup.indexOf('>', lt + 1);
+            index = close === -1 ? length : close + 1;
+            continue;
+        }
+        const gt = markup.indexOf('>', lt);
+        if (gt === -1) {
+            // A stray '<' with no closing '>': treat the rest as text.
+            emit(decodeEntities(markup.slice(lt)));
+            break;
+        }
+        const rawTag = markup.slice(lt + 1, gt);
+        index = gt + 1;
+        const isClose = rawTag[0] === '/';
+        const name = tagName(isClose ? rawTag.slice(1) : rawTag);
+        if (name === '')
+            continue;
+        if (isClose) {
+            popTo(name);
+            continue;
+        }
+        const selfClosing = rawTag.endsWith('/');
+        const inSvg = svgDepth > 0;
+        if (!inSvg) {
+            // HTML implied end tags, minimally: a block start tag closes an open <p>,
+            // and a list/definition item closes its open sibling. Real books rely on
+            // both, and the frame's HTML parse applies them before chunking.
+            const top = stack[stack.length - 1];
+            if (top === 'p' && P_CLOSERS.has(name))
+                stack.pop();
+            else if (name === 'li' && top === 'li')
+                stack.pop();
+            else if ((name === 'dd' || name === 'dt') && (top === 'dd' || top === 'dt'))
+                stack.pop();
+        }
+        // The head never reaches the frame body (only its <link>/<style> move, and
+        // those carry no reading text), so its whole subtree is skipped.
+        if (!inSvg && name === 'head' && !selfClosing) {
+            index = skipBalanced(markup, name, index);
+            continue;
+        }
+        // An <img> renders as an image (zero characters) or becomes its alt text —
+        // the one place extraction *adds* text, mirroring the resource layer.
+        if (!inSvg && name === 'img') {
+            emit(imageReadingText(attributeOf(rawTag, 'src'), attributeOf(rawTag, 'alt'), resolve));
+            continue;
+        }
+        // Discarded-whole elements contribute nothing, exactly like the sanitizer;
+        // raw-text containers jump to their first matching end tag, everything else
+        // to the end tag balancing same-name nesting.
+        const discarded = inSvg ? DISCARDED_SVG_ELEMENTS : DISCARDED_HTML_ELEMENTS;
+        if (discarded.has(name) || name === 'style') {
+            if (selfClosing || (!inSvg && VOID.has(name)))
+                continue;
+            index = RAW_TEXT.has(name) ? findEndTag(markup, name, index) : skipBalanced(markup, name, index);
+            continue;
+        }
+        if (selfClosing || (!inSvg && VOID.has(name)))
+            continue;
+        if (name === 'svg')
+            svgDepth += 1;
+        stack.push(name);
+    }
+    return out;
+}
+/** Decode + extract a section from its raw bytes. */
+export function extractSectionText(bytes, resolve) {
+    return extractText(decodeText(bytes), resolve);
+}
+/**
+ * Index just past the matching `</name>` end tag at or after `from` (raw-text
+ * containers: the first close wins, nothing inside is a tag), or the markup
+ * length when the container is never closed. Case-insensitive on the tag name.
+ */
+function findEndTag(markup, name, from) {
+    const lower = markup.toLowerCase();
+    const needle = `</${name}`;
+    let at = from;
+    for (;;) {
+        const found = lower.indexOf(needle, at);
+        if (found === -1)
+            return markup.length;
+        const after = markup[found + needle.length];
+        // The next char must end the tag name (whitespace or '>'), so </scripting>
+        // does not close <script>.
+        if (after === undefined || after === '>' || /\s/.test(after)) {
+            const gt = markup.indexOf('>', found);
+            return gt === -1 ? markup.length : gt + 1;
+        }
+        at = found + needle.length;
+    }
+}
+/**
+ * Index just past the end tag that balances an already-open `name` element,
+ * counting same-name nesting (a discarded `<select>` may hold another), or the
+ * markup length when it never closes.
+ */
+function skipBalanced(markup, name, from) {
+    const lower = markup.toLowerCase();
+    const open = `<${name}`;
+    const close = `</${name}`;
+    let depth = 1;
+    let at = from;
+    while (depth > 0) {
+        const lt = lower.indexOf('<', at);
+        if (lt === -1)
+            return markup.length;
+        const gt = markup.indexOf('>', lt);
+        if (gt === -1)
+            return markup.length;
+        if (lower.startsWith(close, lt) && endsTagName(markup, lt + close.length)) {
+            depth -= 1;
+        }
+        else if (lower.startsWith(open, lt) && endsTagName(markup, lt + open.length)) {
+            if (markup[gt - 1] !== '/')
+                depth += 1; // a self-closing one opens nothing
+        }
+        at = gt + 1;
+    }
+    return at;
+}
+/** True when the character at `i` terminates a tag name (`>`, `/`, whitespace, EOF). */
+function endsTagName(markup, i) {
+    const char = markup[i];
+    return char === undefined || char === '>' || char === '/' || /\s/.test(char);
+}
+/** The lowercased element name from a raw tag body ('em class="x"' → 'em'). */
+function tagName(body) {
+    let end = 0;
+    while (end < body.length && !/[\s/>]/.test(body[end]))
+        end += 1;
+    return body.slice(0, end).toLowerCase();
+}
+/**
+ * The decoded value of `wanted` in a raw tag body, or `null` when absent.
+ * Handles single/double-quoted and unquoted values and a bare attribute name
+ * (which the DOM reads as the empty string). Entities in the value are decoded,
+ * as an attribute parse would.
+ */
+function attributeOf(rawTag, wanted) {
+    let i = 0;
+    while (i < rawTag.length && !/[\s/]/.test(rawTag[i]))
+        i += 1; // skip the tag name
+    while (i < rawTag.length) {
+        while (i < rawTag.length && /[\s/]/.test(rawTag[i]))
+            i += 1;
+        if (i >= rawTag.length)
+            break;
+        let start = i;
+        while (i < rawTag.length && !/[\s=/]/.test(rawTag[i]))
+            i += 1;
+        const attribute = rawTag.slice(start, i).toLowerCase();
+        while (i < rawTag.length && /\s/.test(rawTag[i]))
+            i += 1;
+        let value = '';
+        if (rawTag[i] === '=') {
+            i += 1;
+            while (i < rawTag.length && /\s/.test(rawTag[i]))
+                i += 1;
+            const quote = rawTag[i];
+            if (quote === '"' || quote === "'") {
+                i += 1;
+                start = i;
+                while (i < rawTag.length && rawTag[i] !== quote)
+                    i += 1;
+                value = rawTag.slice(start, i);
+                i += 1;
+            }
+            else {
+                start = i;
+                while (i < rawTag.length && !/\s/.test(rawTag[i]))
+                    i += 1;
+                value = rawTag.slice(start, i);
+            }
+        }
+        if (attribute === wanted)
+            return decodeEntities(value);
+    }
+    return null;
+}
+const NAMED = new Map([
+    ['amp', '&'],
+    ['lt', '<'],
+    ['gt', '>'],
+    ['quot', '"'],
+    ['apos', "'"],
+    ['nbsp', ' '],
+    ['mdash', '—'],
+    ['ndash', '–'],
+    ['hellip', '…'],
+    ['lsquo', '‘'],
+    ['rsquo', '’'],
+    ['ldquo', '“'],
+    ['rdquo', '”'],
+    ['copy', '©'],
+    ['reg', '®'],
+    ['trade', '™'],
+    ['deg', '°'],
+    ['times', '×'],
+    ['eacute', 'é'],
+    ['egrave', 'è'],
+    ['agrave', 'à'],
+    ['ccedil', 'ç'],
+    ['uuml', 'ü'],
+    [' ', ' '],
+]);
+/**
+ * Decodes numeric (`&#233;`, `&#xe9;`) and the common named HTML entities. An
+ * unknown entity is left verbatim — a book's literal `&` in prose stays `&`.
+ */
+function decodeEntities(text) {
+    if (!text.includes('&'))
+        return text;
+    return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (whole, body) => {
+        if (body[0] === '#') {
+            const code = body[1] === 'x' || body[1] === 'X'
+                ? Number.parseInt(body.slice(2), 16)
+                : Number.parseInt(body.slice(1), 10);
+            if (!Number.isFinite(code) || code < 0 || code > 0x10ffff)
+                return whole;
+            try {
+                return String.fromCodePoint(code);
+            }
+            catch {
+                return whole;
+            }
+        }
+        return NAMED.get(body.toLowerCase()) ?? whole;
+    });
+}
+//# sourceMappingURL=extract.js.map

package/dist/search/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/search/extract.ts"],"names":[],"mappings":"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"}

package/dist/search/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Full-text search: a headless matcher over decoded section text, yielding jumpable
+ * hits. Imports only `src/core` + platform primitives (`DOMParser`, `Intl.Segmenter`,
+ * `TextDecoder`), so it runs under `node:test` with no browser and passes
+ * `npm run check:core`. The whole-book scan (`searchBook`) is a lazy async generator
+ * that never buffers the book whole and cleans up on early `break`.
+ */
+export { searchBook, matchText, type SearchHit, type SearchOptions } from './matcher.ts';
+export { extractText, extractSectionText, decodeSectionBytes, type ReadingResolver } from './extract.ts';
+export { normalizeText, normalizeQuery, type NormalizedText } from './normalize.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/search/index.js

@@ -0,0 +1,11 @@
+/**
+ * Full-text search: a headless matcher over decoded section text, yielding jumpable
+ * hits. Imports only `src/core` + platform primitives (`DOMParser`, `Intl.Segmenter`,
+ * `TextDecoder`), so it runs under `node:test` with no browser and passes
+ * `npm run check:core`. The whole-book scan (`searchBook`) is a lazy async generator
+ * that never buffers the book whole and cleans up on early `break`.
+ */
+export { searchBook, matchText } from './matcher.js';
+export { extractText, extractSectionText, decodeSectionBytes } from './extract.js';
+export { normalizeText, normalizeQuery } from './normalize.js';
+//# sourceMappingURL=index.js.map

package/dist/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAsC,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAwB,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,cAAc,EAAuB,MAAM,gBAAgB,CAAC"}

package/dist/search/matcher.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The headless full-text matcher. Normalized literal substring search over a
+ * section's extracted text, yielding jumpable hits. Imports only `src/core`
+ * (`capturePosition`, `Position`, `Book`, `Section`) and platform primitives, so it
+ * runs under `node:test` with no browser.
+ *
+ * The whole-book scan is a lazy async generator: it decodes and scans one section at
+ * a time and yields hits as it goes, so the book is never buffered whole and a
+ * consumer that `break`s stops the scan (the generator's cleanup runs on return).
+ */
+import { type Book, type Position } from '../core/index.ts';
+/** One search hit: the matched text, a clean context window, and a jumpable position. */
+export interface SearchHit {
+    /** The verbatim matched run, in the section's raw text. */
+    readonly text: string;
+    /**
+     * The match surrounded by context, trimmed to whole words at both ends via
+     * `Intl.Segmenter` — no leading/trailing partial word.
+     */
+    readonly context: string;
+    /**
+     * A content-addressed `Position` at the match, built with `capturePosition`. Pass
+     * it to `reader.goTo(hit.position)` to land on the hit's page.
+     */
+    readonly position: Position;
+    /** 0-based index of the section this hit falls in, in reading order. */
+    readonly sectionIndex: number;
+}
+export interface SearchOptions {
+    /**
+     * Characters of surrounding context to aim for on each side of the match before
+     * word-boundary trimming. Default 40.
+     */
+    readonly contextRadius?: number;
+    /** Locale for word segmentation of the context. Defaults to the runtime default. */
+    readonly locale?: string;
+}
+/**
+ * All hits for `query` within one section's already-extracted `rawText`. Pure over
+ * strings — no I/O — so it is the unit the section scan and the tests both drive.
+ * A blank (whitespace-only or empty) query yields nothing.
+ */
+export declare function matchText(rawText: string, query: string, sectionId: string, sectionIndex: number, options?: SearchOptions): Generator<SearchHit>;
+/**
+ * Lazily scans every section of `book` for `query`, one section at a time, yielding
+ * each hit as it is found. The book is never buffered whole: each section's bytes are
+ * loaded, extracted, matched and released before the next is touched. A consumer that
+ * stops early (`break`/`return`) halts the scan — no later section is loaded.
+ *
+ * `onSection` (test-only instrumentation seam) fires with each section's index the
+ * moment before it is decoded, so a test can prove laziness by counting decodes.
+ */
+export declare function searchBook(book: Book, query: string, options?: SearchOptions & {
+    onSection?: (index: number) => void;
+}): AsyncGenerator<SearchHit>;
+//# sourceMappingURL=matcher.d.ts.map

package/dist/search/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/search/matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAmB,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAgB,MAAM,kBAAkB,CAAC;AAM3F,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;;GAIG;AACH,wBAAiB,SAAS,CACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,aAAkB,GAC1B,SAAS,CAAC,SAAS,CAAC,CA+CtB;AAqDD;;;;;;;;GAQG;AACH,wBAAuB,UAAU,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAa,GAAG;IAAE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GACpE,cAAc,CAAC,SAAS,CAAC,CAgB3B"}

package/dist/search/matcher.js

@@ -0,0 +1,128 @@
+/**
+ * The headless full-text matcher. Normalized literal substring search over a
+ * section's extracted text, yielding jumpable hits. Imports only `src/core`
+ * (`capturePosition`, `Position`, `Book`, `Section`) and platform primitives, so it
+ * runs under `node:test` with no browser.
+ *
+ * The whole-book scan is a lazy async generator: it decodes and scans one section at
+ * a time and yields hits as it goes, so the book is never buffered whole and a
+ * consumer that `break`s stops the scan (the generator's cleanup runs on return).
+ */
+import { capturePosition } from '../core/index.js';
+import { collapseWhitespace as collapse } from '../core/text.js';
+import { extractSectionText } from './extract.js';
+import { normalizeQuery, normalizeText } from './normalize.js';
+const DEFAULT_CONTEXT_RADIUS = 40;
+/**
+ * All hits for `query` within one section's already-extracted `rawText`. Pure over
+ * strings — no I/O — so it is the unit the section scan and the tests both drive.
+ * A blank (whitespace-only or empty) query yields nothing.
+ */
+export function* matchText(rawText, query, sectionId, sectionIndex, options = {}) {
+    const needle = normalizeQuery(query);
+    if (needle === '')
+        return;
+    const { text: haystack, map } = normalizeText(rawText);
+    const radius = options.contextRadius ?? DEFAULT_CONTEXT_RADIUS;
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            return;
+        const end = at + needle.length;
+        // Map the normalized match span back onto the raw text. `map[end]` points at the
+        // start of the character *after* the match, which — when that character is a
+        // collapsed space — lies past a run of raw whitespace; trim it so the matched
+        // text ends on real content. The anchor still starts at `rawStart`.
+        const rawStart = map[at];
+        const rawEnd = trimEnd(rawText, rawStart, map[end]);
+        const matched = rawText.slice(rawStart, rawEnd);
+        // Context window in normalized space, then mapped back and word-trimmed on the
+        // raw text so the shown context carries no partial word at either edge.
+        const ctxNormStart = Math.max(0, at - radius);
+        const ctxNormEnd = Math.min(haystack.length, end + radius);
+        const rawCtxStart = map[ctxNormStart];
+        const rawCtxEnd = map[ctxNormEnd];
+        const context = trimToWords(rawText, rawCtxStart, rawCtxEnd, rawStart, rawEnd, options.locale);
+        yield {
+            text: matched,
+            context,
+            position: capturePosition(rawText, rawStart, sectionId),
+            sectionIndex,
+        };
+        // Advance past this match; guard against a zero-length needle (impossible here,
+        // an empty needle returned above) so the loop always progresses.
+        from = end > at ? end : at + 1;
+    }
+}
+/**
+ * Trims a raw context window `[start, end)` inward to whole-word boundaries via
+ * `Intl.Segmenter`, never cutting into the match span `[matchStart, matchEnd)`. A
+ * word straddling the left edge is dropped forward to its end (the next word's
+ * start); a word straddling the right edge is dropped back to its start. The result
+ * is whitespace-collapsed for a compact one-line context.
+ */
+function trimToWords(text, start, end, matchStart, matchEnd, locale) {
+    // Segment a slice wider than the window so a word straddling an edge is visible
+    // whole. Offsets are relative to the wide slice, so add `lo`.
+    const lo = Math.max(0, Math.min(start, matchStart) - 24);
+    const hi = Math.min(text.length, Math.max(end, matchEnd) + 24);
+    let head = start;
+    let tail = end;
+    for (const seg of wordSegmenter(locale).segment(text.slice(lo, hi))) {
+        if (!seg.isWordLike)
+            continue;
+        const segStart = lo + seg.index;
+        const segEnd = segStart + seg.segment.length;
+        // A word-like segment straddling the left edge: move head to its end (the next
+        // word's start), but never past the match start.
+        if (segStart < start && segEnd > start)
+            head = Math.min(matchStart, segEnd);
+        // A word-like segment straddling the right edge: move tail to its start, but
+        // never before the match end.
+        if (segStart < end && segEnd > end)
+            tail = Math.max(matchEnd, segStart);
+    }
+    return collapse(text.slice(head, tail));
+}
+/** Pull `end` back past any trailing whitespace, never before `start`. */
+function trimEnd(text, start, end) {
+    let at = end;
+    while (at > start && /\s/.test(text[at - 1]))
+        at -= 1;
+    return at;
+}
+let cachedWordSegmenter;
+function wordSegmenter(locale) {
+    if (cachedWordSegmenter === undefined || cachedWordSegmenter.locale !== locale) {
+        cachedWordSegmenter = { locale, segmenter: new Intl.Segmenter(locale, { granularity: 'word' }) };
+    }
+    return cachedWordSegmenter.segmenter;
+}
+/**
+ * Lazily scans every section of `book` for `query`, one section at a time, yielding
+ * each hit as it is found. The book is never buffered whole: each section's bytes are
+ * loaded, extracted, matched and released before the next is touched. A consumer that
+ * stops early (`break`/`return`) halts the scan — no later section is loaded.
+ *
+ * `onSection` (test-only instrumentation seam) fires with each section's index the
+ * moment before it is decoded, so a test can prove laziness by counting decodes.
+ */
+export async function* searchBook(book, query, options = {}) {
+    const needle = normalizeQuery(query);
+    if (needle === '')
+        return;
+    const sections = book.sections;
+    for (let index = 0; index < sections.length; index += 1) {
+        const section = sections[index];
+        options.onSection?.(index);
+        const bytes = await section.load();
+        // The section's own resolver rides along so extraction shows an <img> the
+        // way the frame will: rendered (no text) or substituted by its alt.
+        const rawText = extractSectionText(bytes, section.resolve?.bind(section));
+        for (const hit of matchText(rawText, query, section.id, index, options)) {
+            yield hit;
+        }
+    }
+}
+//# sourceMappingURL=matcher.js.map

package/dist/search/matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.js","sourceRoot":"","sources":["../../src/search/matcher.ts"],"names":[],"mappings":"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"}