wolfy-reader 0.1.0

package/src/reader/input.ts

@@ -0,0 +1,122 @@
+/**
+ * Input intent mapping for the reader facade.
+ *
+ * The sandboxed frame forwards *semantic* gestures — a nav-relevant keydown, a
+ * completed horizontal swipe, a non-link tap with its coords + the frame's
+ * viewport size (see `src/view/frame.ts`, `PROTOCOL_VERSION` 5). This module
+ * turns those into direction-aware navigation intents. It owns no DOM and no
+ * host vocabulary; it is pure geometry + a key table, so it is unit-checkable
+ * and the facade stays thin.
+ *
+ * Reading direction (`Book.direction`) flips the *horizontal* axis only:
+ * in RTL the visual right edge is the earlier page, so a rightward gesture goes
+ * *back* and a leftward gesture goes *forward*. Vertical arrows, PageUp/PageDown
+ * and Home/End are direction-neutral — PageDown always advances reading order,
+ * Home/End are always book start/end.
+ */
+import type { ReadingDirection } from '../core/index.ts';
+
+/** What an input event resolves to. `none` means the event maps to nothing. */
+export type NavIntent = 'next' | 'prev' | 'nextSection' | 'prevSection' | 'start' | 'end' | 'none';
+
+/**
+ * Tap-zone configuration. Each field is the fraction of the frame width [0..1]
+ * marking where a zone ends. `left` is the leftmost fraction that turns to the
+ * left-edge page; `right` is the fraction from which the right-edge page turns;
+ * the band between is inert. Directions are *visual* (left/right of the frame);
+ * RTL mapping is applied afterward. Defaults: left third / right third.
+ */
+export interface TapZones {
+  /** Fraction [0..1]: taps with x < left*width hit the left zone. Default 1/3. */
+  readonly left?: number;
+  /** Fraction [0..1]: taps with x >= right*width hit the right zone. Default 2/3. */
+  readonly right?: number;
+}
+
+/** Per-reader input configuration. All optional; input is enabled by default. */
+export interface InputConfig {
+  /** Keyboard navigation. Default true. */
+  readonly keyboard?: boolean;
+  /** Touch/pointer swipe navigation. Default true. */
+  readonly swipe?: boolean;
+  /** Tap-zone navigation, or its zone geometry. `false` disables tap zones. Default enabled. */
+  readonly tapZones?: TapZones | false;
+}
+
+const DEFAULT_LEFT = 1 / 3;
+const DEFAULT_RIGHT = 2 / 3;
+/** Below this |dx| a swipe is ignored (the frame already thresholds, this guards direction). */
+const SWIPE_MIN = 1;
+
+/** Turn a visual direction ('left'|'right') into a nav intent under `direction`. */
+function edgeIntent(edge: 'left' | 'right', direction: ReadingDirection): NavIntent {
+  // LTR: right edge advances (next), left edge goes back (prev). RTL swaps.
+  const rtl = direction === 'rtl';
+  if (edge === 'right') return rtl ? 'prev' : 'next';
+  return rtl ? 'next' : 'prev';
+}
+
+/**
+ * Map a `KeyboardEvent.key` to a nav intent, direction-aware. Horizontal arrows
+ * flip under RTL; PageUp/PageDown, vertical arrows and Space are reading-order
+ * neutral (Space always advances, Shift+Space always retreats — the near-universal
+ * reader/browser convention); Home/End are always book start/end. The frame
+ * forwards Space as the normalized tokens `'Space'` / `'Shift+Space'` because
+ * `KeyboardEvent.key` is `' '` for both and the wire carries no modifier field;
+ * the raw `' '` spelling is accepted too for host-side callers.
+ */
+export function keyIntent(key: string, direction: ReadingDirection): NavIntent {
+  switch (key) {
+    case 'ArrowRight':
+      return edgeIntent('right', direction);
+    case 'ArrowLeft':
+      return edgeIntent('left', direction);
+    case 'ArrowDown':
+    case 'PageDown':
+    case ' ':
+    case 'Space':
+      return 'next';
+    case 'ArrowUp':
+    case 'PageUp':
+    case 'Shift+ ':
+    case 'Shift+Space':
+      return 'prev';
+    case 'Home':
+      return 'start';
+    case 'End':
+      return 'end';
+    default:
+      return 'none';
+  }
+}
+
+/**
+ * Map a completed swipe's net delta to a nav intent. A leftward swipe (dx < 0)
+ * moves the page contents left → the next visual page; a rightward swipe (dx > 0)
+ * reveals the previous. RTL flips both. dy is accepted for symmetry with the
+ * wire shape but unused: the frame only forwards horizontal-dominant swipes.
+ */
+export function swipeIntent(dx: number, _dy: number, direction: ReadingDirection): NavIntent {
+  if (Math.abs(dx) < SWIPE_MIN) return 'none';
+  return dx < 0 ? edgeIntent('right', direction) : edgeIntent('left', direction);
+}
+
+/**
+ * Map a tap to a nav intent using the zone fractions, direction-aware. The tap's
+ * x is normalized by the frame width; a tap in the left zone turns to the
+ * left-edge page and the right zone to the right-edge page (both flipped under
+ * RTL); the center band is inert.
+ */
+export function tapIntent(
+  tap: { x: number; width: number },
+  zones: TapZones,
+  direction: ReadingDirection,
+): NavIntent {
+  if (tap.width <= 0) return 'none';
+  const fraction = tap.x / tap.width;
+  const left = zones.left ?? DEFAULT_LEFT;
+  const right = zones.right ?? DEFAULT_RIGHT;
+  if (fraction < left) return edgeIntent('left', direction);
+  if (fraction >= right) return edgeIntent('right', direction);
+  return 'none';
+}

package/src/search/extract.ts

@@ -0,0 +1,403 @@
+/**
+ * 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,
+  type ReadingResolver,
+} from '../core/reading-text.ts';
+import { decodeText } from '../core/text.ts';
+
+export type { ReadingResolver } from '../core/reading-text.ts';
+
+/** Decodes section bytes honouring the byte-order marks EPUB allows. */
+export { decodeText as decodeSectionBytes } from '../core/text.ts';
+
+/**
+ * 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: string, resolve?: ReadingResolver): string {
+  let out = '';
+  let index = 0;
+  /** Open non-void elements. `head` and skipped containers never land here. */
+  const stack: string[] = [];
+  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 = (): boolean => {
+    const top = stack[stack.length - 1];
+    return top === undefined || top === 'html' || top === 'body';
+  };
+  const emit = (text: string): void => {
+    if (text === '') return;
+    if (atTopLevel() && text.trim().length === 0) return;
+    out += text;
+  };
+  const popTo = (name: string): void => {
+    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: Uint8Array, resolve?: ReadingResolver): string {
+  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: string, name: string, from: number): number {
+  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: string, name: string, from: number): number {
+  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: string, i: number): boolean {
+  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: string): string {
+  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: string, wanted: string): string | null {
+  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: ReadonlyMap<string, string> = 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: string): string {
+  if (!text.includes('&')) return text;
+  return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (whole, body: string) => {
+    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;
+  });
+}

package/src/search/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';