wolfy-reader 0.1.0

package/dist/index.js

@@ -0,0 +1,28 @@
+/*! wolfy-reader v0.1.0 | @license MIT | (c) Vitaliy Tkachuk | github.com/vitaliy-tkachuk/wolfy-reader */
+/**
+ * The package root: the browser-facing reader facade plus the headless core it
+ * operates on.
+ *
+ *   import { open, render } from 'wolfy-reader';
+ *   import { epub } from 'wolfy-reader/epub';
+ *
+ * Core travels with the facade because `render` takes a `Book` and `open` is the
+ * only public way to make one — splitting them would make the common case a
+ * three-import dance, and the facade's own surface already names `Position`,
+ * `TocItem` and `SentenceRange` in its signatures.
+ *
+ * Both re-exports resolve to the same emitted modules as `wolfy-reader/core`, so
+ * there is one `open`, one `Position` model and one set of error constructors
+ * however a consumer reaches them — `instanceof BookError` holds across entries.
+ *
+ * Headless consumers should import `wolfy-reader/core` instead. This root reaches
+ * `src/layout` and `src/view`; it is import-safe under Node today and the pack
+ * fidelity check keeps it that way, but only `/core` carries the guarantee.
+ *
+ * Format decoders are deliberately absent: each is its own subpath because their
+ * closures differ by an order of magnitude — only `epub` pulls the ZIP reader —
+ * and `open(input, { formats })` takes an explicit list by design.
+ */
+export * from './core/index.js';
+export * from './reader/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/layout/chunk.d.ts

@@ -0,0 +1,51 @@
+/** The minimal shape the boundary rules read from each top-level node. */
+export interface ChunkNode {
+    /** Uppercase tag name for elements, `'#text'` for text nodes. */
+    readonly tag: string;
+    /** `textContent.length` of this node. */
+    readonly chars: number;
+    /** Serialized markup — `outerHTML` for elements, escaped text for text nodes. */
+    readonly html: string;
+}
+export interface Chunk {
+    readonly html: string;
+    /** Total characters of text this chunk holds. */
+    readonly chars: number;
+    /** Number of top-level nodes in this chunk. */
+    readonly nodes: number;
+}
+export interface ChunkStats {
+    readonly topLevelNodes: number;
+    readonly oversizedElements: number;
+    readonly largestElementChars: number;
+    readonly headingsDeferred: number;
+    readonly atomicOversized: number;
+    readonly bareTextNodes: number;
+}
+export interface ChunkResult {
+    readonly chunks: readonly Chunk[];
+    readonly stats: ChunkStats;
+}
+/** Default chunk budget in characters. The whole tradeoff dial; see layout.md. */
+export declare const DEFAULT_CHUNK_CHARS = 8000;
+/**
+ * Splits a top-level node list into chunks at flow boundaries, accumulating
+ * children until `targetChars` of text is reached.
+ *
+ * - Split only between top-level (depth-1) children; never descend.
+ * - An element larger than the budget is emitted whole as its own chunk (the
+ *   budget is advisory, not a cap) — descending would put a page break
+ *   mid-paragraph.
+ * - Never end a chunk on a heading or `<hr>`; defer it to the next chunk.
+ * - Bare text nodes are glued to the open chunk; whitespace-only ones are
+ *   dropped by `chunkElement` before this runs.
+ */
+export declare function chunkNodes(nodes: readonly ChunkNode[], targetChars?: number): ChunkResult;
+/**
+ * Adapts a live DOM element (a section body) into the `ChunkNode` list the
+ * boundary rules read, then chunks it. Whitespace-only bare text nodes are
+ * dropped here — they carry no block box and would strand against a formatting
+ * context they did not come from.
+ */
+export declare function chunkElement(body: Element, targetChars?: number): ChunkResult;
+//# sourceMappingURL=chunk.d.ts.map

package/dist/layout/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/layout/chunk.ts"],"names":[],"mappings":"AAiBA,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAWxC;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,WAAW,SAAsB,GAAG,WAAW,CAmEtG;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,SAAsB,GAAG,WAAW,CAiB1F"}

package/dist/layout/chunk.js

@@ -0,0 +1,131 @@
+/**
+ * Chunk-boundary rules for the paginator, derived from real EPUB markup (item8
+ * of gutenberg-pride-and-prejudice.epub: 571 top-level blocks, 552 `<p>`, max
+ * nesting depth 5), not from theory.
+ *
+ * A chunk boundary becomes a *forced page break*, because each chunk is laid out
+ * as its own multi-column formatting context (layout containment forbids a
+ * `content-visibility` box fragmenting across columns). So these rules answer
+ * "where is a forced page break acceptable", not merely "where is the DOM
+ * splittable".
+ *
+ * The rules run over a structural view of a top-level node list — `ChunkNode` —
+ * rather than the DOM directly, so they are pure and unit-testable under
+ * `node:test`. `chunkElement` adapts a real DOM element to that view.
+ */
+import { escapeXmlText } from '../core/text.js';
+/** Default chunk budget in characters. The whole tradeoff dial; see layout.md. */
+export const DEFAULT_CHUNK_CHARS = 8000;
+// Splitting *between* these is fine; splitting *inside* one is not — each carries
+// structure (row alignment, list numbering, preformatted whitespace) a second
+// formatting context would restate from scratch.
+const ATOMIC = new Set(['TABLE', 'PRE', 'OL', 'UL', 'DL', 'FIGURE', 'BLOCKQUOTE', 'SVG', 'MATH']);
+// A chunk must never end on one of these: the boundary is a page break, and a
+// heading (or rule) stranded at the foot of a page is the classic orphan.
+const NEVER_LAST = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HR']);
+/**
+ * Splits a top-level node list into chunks at flow boundaries, accumulating
+ * children until `targetChars` of text is reached.
+ *
+ * - Split only between top-level (depth-1) children; never descend.
+ * - An element larger than the budget is emitted whole as its own chunk (the
+ *   budget is advisory, not a cap) — descending would put a page break
+ *   mid-paragraph.
+ * - Never end a chunk on a heading or `<hr>`; defer it to the next chunk.
+ * - Bare text nodes are glued to the open chunk; whitespace-only ones are
+ *   dropped by `chunkElement` before this runs.
+ */
+export function chunkNodes(nodes, targetChars = DEFAULT_CHUNK_CHARS) {
+    let oversizedElements = 0;
+    let largestElementChars = 0;
+    let headingsDeferred = 0;
+    let atomicOversized = 0;
+    let bareTextNodes = 0;
+    const chunks = [];
+    let current = [];
+    let currentChars = 0;
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        chunks.push({
+            html: current.map((node) => node.html).join(''),
+            chars: currentChars,
+            nodes: current.length,
+        });
+        current = [];
+        currentChars = 0;
+    };
+    for (const node of nodes) {
+        if (node.tag === '#text')
+            bareTextNodes += 1;
+        if (node.chars > largestElementChars)
+            largestElementChars = node.chars;
+        if (node.chars >= targetChars) {
+            flush();
+            oversizedElements += 1;
+            if (ATOMIC.has(node.tag))
+                atomicOversized += 1;
+            current = [node];
+            currentChars = node.chars;
+            flush();
+            continue;
+        }
+        if (currentChars > 0 && currentChars + node.chars > targetChars) {
+            const deferred = [];
+            while (current.length > 1 && NEVER_LAST.has(current[current.length - 1].tag)) {
+                const moved = current.pop();
+                currentChars -= moved.chars;
+                deferred.unshift(moved);
+                headingsDeferred += 1;
+            }
+            flush();
+            for (const moved of deferred) {
+                current.push(moved);
+                currentChars += moved.chars;
+            }
+        }
+        current.push(node);
+        currentChars += node.chars;
+    }
+    flush();
+    return {
+        chunks,
+        stats: {
+            topLevelNodes: nodes.length,
+            oversizedElements,
+            largestElementChars,
+            headingsDeferred,
+            atomicOversized,
+            bareTextNodes,
+        },
+    };
+}
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+/**
+ * Adapts a live DOM element (a section body) into the `ChunkNode` list the
+ * boundary rules read, then chunks it. Whitespace-only bare text nodes are
+ * dropped here — they carry no block box and would strand against a formatting
+ * context they did not come from.
+ */
+export function chunkElement(body, targetChars = DEFAULT_CHUNK_CHARS) {
+    const nodes = [];
+    for (const node of Array.from(body.childNodes)) {
+        if (node.nodeType === ELEMENT_NODE) {
+            const element = node;
+            nodes.push({
+                tag: element.tagName.toUpperCase(),
+                chars: element.textContent?.length ?? 0,
+                html: element.outerHTML,
+            });
+        }
+        else if (node.nodeType === TEXT_NODE) {
+            const text = node.textContent ?? '';
+            if (text.trim().length === 0)
+                continue;
+            nodes.push({ tag: '#text', chars: text.length, html: escapeXmlText(text) });
+        }
+    }
+    return chunkNodes(nodes, targetChars);
+}
+//# sourceMappingURL=chunk.js.map

package/dist/layout/chunk.js.map

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

package/dist/layout/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The paginator engine: wraps a {@link ContentHost} over a container element and
+ * exposes page-oriented navigation, page↔`Position` mapping, and progress on top
+ * of the frame's chunked layout. This is the engine the reader facade (M2-4)
+ * consumes; it owns no host vocabulary and never fetches or persists.
+ *
+ * Layout, measurement, chunking, and eviction all live in the frame (Slice 1 —
+ * `ContentHost`); this module orchestrates them and bridges page geometry to the
+ * headless `Position` model in `src/core`. Core is *called*, never changed: a page
+ * maps to a `Position` through `offsetOfPage` → `capturePosition`, and a
+ * `Position` maps back through `resolvePosition` → `pageOfOffset`.
+ */
+import { type Position, type Section } from '../core/index.ts';
+import { ContentHost, type ContentHostOptions } from '../view/host.ts';
+import type { LayoutMode, PaginateOptions, PaginationState } from '../view/protocol.ts';
+export type { LayoutMode, PaginateOptions, PaginationState } from '../view/protocol.ts';
+/**
+ * The parts of {@link PaginateOptions} a caller may set without also supplying
+ * the viewport geometry, which the paginator measures from its container. Every
+ * field is optional; unset fields fall back to the paginator defaults.
+ */
+export interface PaginateRequest {
+    readonly mode?: LayoutMode;
+    /** Page box width in CSS px. Defaults to the container's client width. */
+    readonly pageWidth?: number;
+    /** Page box height in CSS px. Defaults to the container's client height. */
+    readonly pageHeight?: number;
+    readonly columnGap?: number;
+    readonly chunkChars?: number;
+    readonly windowChunks?: number;
+    /** Text columns per page (1 or 2). Defaults to 1. */
+    readonly columnCount?: number;
+}
+/**
+ * Chapter-local layout state: the current page, the total (estimate or firm),
+ * and whether the total has been measured across every chunk yet.
+ */
+export interface ChapterProgress {
+    readonly mode: LayoutMode;
+    /** 0-based page currently shown. */
+    readonly page: number;
+    /** Total pages — an estimate until {@link firm}. */
+    readonly totalPages: number;
+    /** True once every chunk is measured; false while {@link totalPages} churns. */
+    readonly firm: boolean;
+    /** Fraction through the chapter, 0..1. */
+    readonly fraction: number;
+    readonly realizedChunks: number;
+    readonly totalChunks: number;
+}
+/**
+ * Where the reader is in the whole book. Section counts come from the facade;
+ * only the current section is laid out, so any span across other sections is an
+ * even-weight approximation — {@link approximate} says so.
+ */
+export interface BookProgress extends ChapterProgress {
+    /** 0-based index of the current section in reading order. */
+    readonly sectionIndex: number;
+    /** Total sections in the book. */
+    readonly sectionCount: number;
+    /** Fraction through the book, 0..1 — even-weight across sections. */
+    readonly bookFraction: number;
+    /** Always true: sibling sections are unlaid, so the book span is an estimate. */
+    readonly approximate: true;
+}
+export interface PaginatorDiagnostics {
+    readonly domNodes: number;
+    readonly realizedChunks: number;
+    readonly totalChunks: number;
+}
+/** Something went wrong driving the paginator; never a book decoding failure. */
+export declare class PaginatorError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Drives chunked pagination of one section at a time inside a sandboxed frame.
+ *
+ * Lifecycle: construct over a container, {@link paginate} a section, navigate
+ * with {@link goToPage}/{@link nextPage}/{@link previousPage}, map pages to
+ * `Position`s, and {@link destroy} to tear the frame down. A single instance
+ * paginates successive sections in turn; re-paginating replaces the active one.
+ */
+export declare class Paginator {
+    #private;
+    constructor(container: HTMLElement, options?: ContentHostOptions);
+    /** The underlying host, for callers that need the raw frame surface. */
+    get host(): ContentHost;
+    /** The section currently laid out, or `null` before the first {@link paginate}. */
+    get section(): Section | null;
+    /** The effective options of the current layout, or `null` before {@link paginate}. */
+    get options(): PaginateOptions | null;
+    /** The last pagination state, or `null` before {@link paginate}. */
+    get state(): PaginationState | null;
+    /** The current 0-based page. */
+    get page(): number;
+    /**
+     * Chunks and lays out `section` under `request` (merged with the paginator
+     * defaults and the container's measured viewport), resets to page 0, and
+     * returns the resulting state. The page count starts as an estimate; call
+     * {@link refine} to firm it up. Pass `mode: 'scrolled'` for scrolled layout.
+     */
+    paginate(section: Section, request?: PaginateRequest): Promise<PaginationState>;
+    /**
+     * Re-lays the current section (after a viewport or typography change) and
+     * returns the fresh state. The caller preserving position across the relayout
+     * should {@link positionOfPage} before and {@link pageOfPosition} after. Text
+     * is unchanged, so its cache survives.
+     */
+    relayout(): Promise<PaginationState>;
+    /**
+     * Re-lays the current section in a different mode, preserving the reading
+     * position across the switch: it captures a `Position` for the current page,
+     * re-paginates, then seeks back to the page that `Position` now resolves to.
+     * Returns the new state. A resolution miss (rare — same text, same session)
+     * degrades to page 0.
+     */
+    switchMode(mode: LayoutMode): Promise<PaginationState>;
+    /**
+     * Re-paginates the current section at the container's *current* size, preserving
+     * the reading place. Page geometry is captured once at `paginate` time from the
+     * container, so a container that later resizes leaves the frame's content at the
+     * old size — it scrolls (shrunk) or leaves a gap (grown); this re-reads the size
+     * and re-flows. A no-op (returns `null`) when the size is unchanged or the
+     * container is unmeasurable (0×0, e.g. `display:none`), so a `ResizeObserver` may
+     * call it on every notification without churn. Mirrors {@link switchMode}: capture
+     * a `Position`, re-paginate, seek back (a resolution miss degrades to page 0).
+     */
+    resize(): Promise<PaginationState | null>;
+    /**
+     * Drives the estimate toward the true count by re-measuring. In paginated mode
+     * the frame refines the count as chunks realize; a `relayout` forces that
+     * measurement. Returns the (possibly firm) state. Idempotent once firm.
+     */
+    refine(): Promise<PaginationState>;
+    /** Seeks to a 0-based page, clamping to range. Returns the page actually shown. */
+    goToPage(page: number): Promise<number>;
+    /** Turns one page forward, clamped at the last page. Returns the new page. */
+    nextPage(): Promise<number>;
+    /** Turns one page back, clamped at page 0. Returns the new page. */
+    previousPage(): Promise<number>;
+    /**
+     * The `Position` anchored at the start of `page`: page → character offset via
+     * `offsetOfPage`, then `capturePosition(text, offset, sectionId)` over the
+     * section text. An empty page (offset -1) captures at offset 0.
+     */
+    positionOfPage(page: number): Promise<Position>;
+    /**
+     * The `Position` anchored over a frame-supplied UTF-16 offset range on the
+     * section text — the bridge behind selection reporting. The frame computes the
+     * range against the same tiled section text this measures against, so the
+     * `start` offset is captured directly with `capturePosition` (which takes a
+     * UTF-16 offset). The quote spans the whole selection (`start`..`end`), not a
+     * fixed default, so a host that highlights the returned Position via `decorate`
+     * paints the entire selection rather than only its first ~32 graphemes; resolving
+     * it back to a page still keys off the anchor's start.
+     */
+    positionOfOffsetRange(start: number, end: number): Promise<Position>;
+    /**
+     * The 0-based page painting `position`: `resolvePosition` against the section
+     * text yields a character offset, then `pageOfOffset` maps it to a page.
+     * Returns -1 when the anchor no longer resolves (the caller degrades softly).
+     *
+     * Note the offset spaces differ: `resolvePosition` returns a *grapheme* index,
+     * while `pageOfOffset` speaks UTF-16 code units. They coincide for BMP text and
+     * for a text whose graphemes are all single code units; the conversion below
+     * maps grapheme index back to a code-unit offset so multi-unit clusters map
+     * correctly.
+     */
+    pageOfPosition(position: Position): Promise<number>;
+    /**
+     * The 0-based page painting the element carrying `elementId`, or -1 when no
+     * element in the section carries that id (the caller degrades softly). Bridges
+     * fragment anchoring: `offsetOfElementId` in the frame yields the element's
+     * character offset, then `pageOfOffset` maps it to a page.
+     */
+    pageOfElementId(elementId: string): Promise<number>;
+    /**
+     * Draws a decoration over the range `position` resolves to in the current section,
+     * and holds the intent so it survives a re-layout. Draw-only: the paginator keeps
+     * only the in-memory intent (id → position + class) and never persists it. The
+     * `position` is resolved against the frame-measured section text; its resolved
+     * grapheme span is converted to a UTF-16 offset range the frame paints over. A
+     * soft-miss — the anchor no longer resolves, or belongs to a section other than the
+     * one laid out — draws nothing and throws nothing; the intent is still retained so a
+     * later re-layout that brings the anchor back into view redraws it.
+     */
+    decorate(decorationId: string, position: Position, className: string): Promise<void>;
+    /** Removes a decoration and drops its intent. A no-op for an unknown id. */
+    undecorate(decorationId: string): Promise<void>;
+    /** Within-chapter progress: current page, total (estimate/firm), and fraction. */
+    chapterProgress(): ChapterProgress;
+    /**
+     * Within-book progress. The facade supplies the current section's index and the
+     * book's section count; only this section is laid out, so the book fraction is
+     * an even-weight approximation across sections and {@link BookProgress.approximate}
+     * is always true.
+     */
+    bookProgress(sectionIndex: number, sectionCount: number): BookProgress;
+    /**
+     * Applies a new appearance theme stylesheet (see `themeStyleSheet`) to the
+     * current section, preserving the reading position across the swap. A theme is
+     * colours + background only, so chunk geometry is invariant under it: the same
+     * markup re-lays out to the same page count and the captured `Position` resolves
+     * back to the exact same page — the reader's place is held, not reset to 0 and
+     * not drifted, and the text does not reflow. The theme lives in the srcdoc (not
+     * over the wire), so it re-assembles the document; because geometry is invariant
+     * the anchor page is restored precisely. Before the first `paginate` it only
+     * records the theme for the next render.
+     *
+     * A no-op when the stylesheet is unchanged, so re-issuing the same appearance is
+     * free.
+     */
+    setThemeCss(themeCss: string | undefined): Promise<void>;
+    /**
+     * Applies a live appearance change that may re-flow the layout — a new
+     * appearance stylesheet (font/size/line-height/alignment/hyphenation) and/or a
+     * new `columnCount` — preserving the reading position across it. Unlike
+     * {@link setThemeCss} (colours only, geometry invariant), a reflowing knob
+     * changes chunk geometry, so this reuses the same capture → re-layout → resolve →
+     * restore machinery as {@link switchMode}: it captures a `Position` for the
+     * current page, re-paginates with the new stylesheet and column count, and seeks
+     * back to the page that `Position` now resolves to. A same-text resolution miss
+     * degrades to page 0. Before the first `paginate` it only records the stylesheet
+     * for the next render. A no-op (same stylesheet, same column count) short-
+     * circuits, so re-issuing the same appearance is free.
+     */
+    applyAppearance(themeCss: string | undefined, geometry?: {
+        columnCount?: number;
+        columnGap?: number;
+    }): Promise<void>;
+    /** Frame-side counts, for eviction/memory checks. Eviction itself lives in-frame. */
+    diagnostics(): Promise<PaginatorDiagnostics>;
+    /** The section's concatenated chunk text, as the frame measures it (cached). */
+    sectionText(): Promise<string>;
+    /** Tears down the underlying host and frame. Idempotent. */
+    destroy(): void;
+}
+//# sourceMappingURL=index.d.ts.map

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

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