wolfy-reader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitaliy Tkachuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# wolfy-reader
+
+Read ebooks in the browser — with pages that turn, text you can search, and typography you can change without losing your place.
+
+A from-scratch, MIT-licensed, ESM-only TypeScript reading engine for EPUB, FB2 and plain text. Bytes in, a `Book` out, and a real reading view: paginated and scrolled modes, table-of-contents and link navigation, full-text search, live theme and typography controls, selection events and decorations. Zero runtime dependencies, and untrusted book content renders inside a hardened sandboxed iframe.
+
+## Install
+
+```bash
+npm install wolfy-reader
+```
+
+## Quickstart
+
+```ts
+import { open, render } from 'wolfy-reader';
+import { epub } from 'wolfy-reader/epub';
+
+// Bytes in: ArrayBuffer | Blob (a File is one) | { size, read(offset, length) }.
+// The library never fetches — you hand it the bytes.
+const book = await open(file, { formats: [epub] });
+
+console.log(book.metadata.title, book.sections.length);
+
+const reader = render(book, document.getElementById('reader')!, {
+  mode: 'paginated',
+  theme: 'sepia',
+  fontSize: 19,
+});
+
+reader.on('ready', (at) => console.log(`page ${at.page + 1} of ${at.totalPages}`));
+
+await reader.next();               // turn a page
+await reader.goTo(book.toc[0]!);   // jump to a chapter
+await reader.back();               // undo that jump — there is a back-stack
+```
+
+Formats are explicit: `open` takes the list you pass it, so a text-only app never pulls the EPUB decoder or the ZIP reader. `render` returns synchronously and paints asynchronously — the `ready` event is the first painted page.
+
+**Change how it looks, keep the place:**
+
+```ts
+await reader.setAppearance({ fontSize: 24, lineHeight: 1.6, margin: 48 });
+await reader.setMode('scrolled');
+```
+
+Both re-flow the book and then put you back where you were reading. This is a contract, not a best effort: the paragraph at the top of your page is still on your page afterwards, held by a content anchor rather than a page number, and proven by a browser suite that runs every knob against real books.
+
+**Search the whole book, lazily:**
+
+```ts
+for await (const hit of reader.search('whale')) {
+  console.log(hit.context);        // the match, trimmed to whole words
+  await reader.goTo(hit.position); // land on its page
+  break;
+}
+```
+
+**Highlight a selection:**
+
+```ts
+import { serializePosition } from 'wolfy-reader';
+
+reader.on('selection', async ({ text, position }) => {
+  await reader.decorate('note-1', position, { className: 'my-highlight' });
+  localStorage.setItem('note-1', serializePosition(position)); // your storage, not ours
+});
+```
+
+The library *draws* decorations and never stores them. A `Position` serializes to one opaque string you persist yourself and hand back to `decorate` or `goTo` next time.
+
+**Decode without a DOM:**
+
+```ts
+import { open } from 'wolfy-reader/core';
+import { text } from 'wolfy-reader/text';
+
+const book = await open(bytes, { formats: [text] });
+```
+
+`wolfy-reader/core` is guaranteed headless — nothing reachable from it touches `document` or `window`, enforced by a static check in CI — so it runs under Node or a worker.
+
+## What you get
+
+- **Two reading modes** — paginated with real page turns, or continuous scroll, switchable at runtime.
+- **Navigation** — nested TOC, in-book links, and a back-stack for jumps.
+- **Full-text search** across the whole book, streaming as sections are scanned, with jumpable hits.
+- **Live appearance** — theme, font family and size, line height, margins, one or two columns, justification, hyphenation. Every knob preserves position.
+- **Selection events and decorations** — draw styled overlays over any anchored range; the library never stores annotation data.
+- **Sentence ranges** — `reader.sentences()` returns each sentence with a `Position`, so a host can drive a speech engine sentence by sentence. The library speaks nothing.
+- **Input handled** — keyboard, tap zones and swipe, all configurable.
+- **Typed failures** — every error extends `BookError` (`UnrecognizedFormatError`, `CorruptContainerError`, `EncryptedContentError`), so hosts catch by class.
+
+## Stability contract
+
+**The `Book` model and the `Position` format are the promise. Everything else may churn.**
+
+Names in the core model are treated as unrenameable, and a reading position serializes to a version-prefixed opaque string a host persists verbatim and never parses — so positions stored today keep resolving as the format evolves. The reader facade grows additively (new methods, never renamed or removed ones).
+
+The project lives honestly in `0.x` until the model has survived a real consumer. Until `1.0`, a breaking change bumps the minor.
+
+## Browser support
+
+Browsers with `DecompressionStream` — **Chrome 80+, Safari 16.4+, Firefox 113+**. The engine is built on platform primitives (`DecompressionStream`, `DOMParser`, `TextDecoder`, `Intl.Segmenter`, CSS multi-column), which is also what keeps it small.
+
+ESM only — no CJS build, no bundler required. The headless `wolfy-reader/core` entry also runs under Node.
+
+## Zero runtime dependencies
+
+`dependencies` is empty and stays empty, permanently. Not "few" — none. CI fails the build if anything is added, and a pack-fidelity check installs the published tarball into a scratch project to prove it.
+
+Dev dependencies exist (TypeScript, Playwright, esbuild, `@types/node`); none of them ship to you.
+
+Published weight, minified and gzipped:
+
+| Import | Size |
+| --- | --- |
+| `wolfy-reader` | ~30 kB |
+| `wolfy-reader/core` | ~2.3 kB |
+| `wolfy-reader/epub` | ~6.6 kB |
+| `wolfy-reader/fb2` | ~3.7 kB |
+| `wolfy-reader/text` | ~1.4 kB |
+
+Each subpath has a budget CI refuses to exceed. Format decoders are separate entries on purpose — only `epub` carries the ZIP reader.
+
+## Security
+
+Book content is untrusted input, and it renders behind three independent defences:
+
+- a `sandbox="allow-scripts"` iframe **without** `allow-same-origin`, so the frame's origin is opaque and it can reach nothing of yours;
+- allowlist sanitization of every element and attribute before the markup is assembled;
+- a per-render `Content-Security-Policy` of `default-src 'none'`, with the book's own images, stylesheets and fonts served as `data:` URLs.
+
+Host and frame talk over one typed, versioned, validated `postMessage` protocol. The layers are not redundant — see [`docs/domains/view.md`](docs/domains/view.md) for why each is load-bearing.
+
+## Formats and legal position
+
+EPUB 2 and 3 (reflowable), FB2, and plain text today; MOBI/AZW3 is planned. Fixed-layout books are *detected* and reported so a host can refuse them — rendering stays reflowable, permanently.
+
+**DRM-free books only.** DRM is permanently out of scope: nothing here decrypts, circumvents, or interoperates with a DRM scheme.
+
+Formats were learned from specifications — the W3C EPUB specs, the MobileRead format wiki, the PalmDB spec — never from GPL source. No code is taken from epub.js, foliate-js, Readium, PDF.js or JSZip.
+
+## Package surface
+
+Five subpaths, written longhand with no wildcards — internal modules are not importable:
+
+| Subpath | Contains |
+| --- | --- |
+| `wolfy-reader` | `render` + the reader facade, plus everything in `/core` |
+| `wolfy-reader/core` | `open`, the `Book` model, `Position`, typed errors — guaranteed headless |
+| `wolfy-reader/epub` | the EPUB decoder |
+| `wolfy-reader/fb2` | the FB2 decoder |
+| `wolfy-reader/text` | the plain-text decoder |
+
+## License
+
+MIT © Vitaliy Tkachuk
+
+---
+
+# Development
+
+Everything below is for working *on* the library rather than with it.
+
+## Stack
+
+- Language: TypeScript — ESM only (`"type": "module"`), no CJS build
+- Build system: TypeScript compiler (`tsc`), no bundler; `node:test` for tests, Playwright for browser tests (dev-only)
+- Package registry: npm — `wolfy-reader` (unscoped)
+- Target platforms / runtimes: Browsers with `DecompressionStream` — Chrome 80+, Safari 16.4+, Firefox 113+
+
+## Getting Started
+
+```bash
+npm install
+npm run fetch-corpus # download the gitignored test corpus (Gutenberg + Standard Ebooks + W3C)
+npm test             # node:test suite, headless — includes the differential decode suite
+npm run test:browser # Playwright suites for the sandboxed frame
+npm run typecheck    # tsc --noEmit
+npm run check:core   # fail if src/core reaches src/layout or src/view
+npm run check:guards # fail if dependencies grew or consumer vocabulary leaked in
+npm run build        # tsc -> dist (plain ESM + .d.ts + sourcemaps), then the @license banner
+npm run check:size   # gzipped bundle budget per published subpath (needs a build)
+npm run check:pack   # pack, install the tarball, import and typecheck every subpath
+npm run bench        # pagination benchmark (needs the corpus)
+```
+
+GitHub Actions runs all of the above on every push to `main` and every pull
+request; the Playwright suites run on pull requests only. Node is pinned in
+`.nvmrc` so local and CI cannot drift. See
+[`docs/domains/release.md`](docs/domains/release.md) for what each guard defends
+and why the browser tier is PR-only.
+
+`npm run check:pack` is the only check that exercises the *published* surface: the
+demo and the test suites import `/src/...` by path, which the `exports` map does not
+govern, so a packaging fault is invisible to them. Run it before any release — see
+[`docs/domains/release.md`](docs/domains/release.md).
+
+The differential decode suite (`test/differential.test.ts`) proves the decoders
+agree: for each title shipped as both EPUB and TXT, it decodes each, strips
+boilerplate, normalizes, and asserts the prose matches across formats. It is
+headless and **skips gracefully when the corpus is absent** — run `npm run
+fetch-corpus` first to exercise it. This is the safety net MOBI/AZW3 will be
+built against.
+
+### Setup on a new machine
+
+A clone gives you the source, the docs, the committed fixtures and the knowledge graph. Four things are deliberately not in the repo and are set up per machine:
+
+```bash
+npm install                      # 1. required
+npx playwright install chromium  # 2. required for `npm run test:browser` (~115 MB)
+npm run fetch-corpus             # 3. optional — real books, ~30 MB, gitignored
+graphify hook install            # 4. optional — per-clone, see Knowledge graph below
+```
+
+1. **`npm install`** — `dependencies` is permanently empty; this installs the dev toolchain only.
+2. **`npx playwright install chromium`** — the `playwright` package has no postinstall step, so `npm install` alone leaves you with no browser and `npm run test:browser` fails. Browser suites launch full Chromium (`channel: 'chromium'`), not the headless shell.
+3. **`npm run fetch-corpus`** — downloads Project Gutenberg + Standard Ebooks titles into gitignored `test/corpus/`. Skipping it is safe: corpus-backed tests skip gracefully by rule and `npm test` stays green. Without it, `npm run bench` skips and the benchmark fixtures cannot be generated.
+4. **`graphify hook install`** — the git hooks that rebuild the knowledge graph are local-only; a fresh clone has none until you install them.
+
+Everything above is regenerable. The one file that is not in the repo and cannot be rebuilt is the local `PLAN.md` implementation plan — copy it across by hand if you are moving machines mid-project.
+
+> Benchmark timings recorded in [`docs/domains/layout.md`](docs/domains/layout.md) are machine-specific. On different hardware, re-baseline with `npm run bench` and compare the chunked-vs-naive *ratios* (3–7x, far above machine variance) rather than the absolute milliseconds.
+
+## Running Locally
+
+```bash
+npm run demo
+```
+
+This starts a dependency-free dev server (Node built-ins only) and prints the URL — `http://localhost:8080/` by default, or the next free port if 8080 is busy. It serves exactly two directories: `demo/` (at `/`, so `/` opens the demo) and `src/` (at `/src/`, so the demo can import library modules); no other repo path is reachable. `.ts` files are served with type annotations stripped (`node:module`'s `stripTypeScriptTypes`), so the browser runs the TypeScript sources directly — no bundler, no build step.
+
+The demo is the primary development surface: pick an EPUB and it opens the book through the public API and shows what the decoder produced — metadata and cover, the nested table of contents, and the reading order. Clicking a chapter renders it as live markup inside the hardened sandboxed frame, with the book's own stylesheets and images, next to a panel listing everything the sanitizer removed and everything the Content Security Policy blocked. Decode failures surface as the library's typed errors by class name. It stays framework-free by rule. Opening `demo/index.html` as a `file://` URL does not work — browsers block ES module loading over `file://`.
+
+## Building & Releasing
+
+```bash
+npm run build      # tsc -> dist (plain ESM + .d.ts + sourcemaps), then the @license banner
+npm run check:pack # pack, install the tarball, import and typecheck every subpath
+```
+
+Releases are pull requests. [release-please](https://github.com/googleapis/release-please)
+keeps one open on `main`, carrying the version bump and the `CHANGELOG.md` entry it
+derives from the Conventional Commit subjects since the last tag. Merging it tags the
+release and publishes to npm from GitHub Actions, authenticated by OIDC trusted
+publishing with provenance — there is no `NPM_TOKEN` in this repository and no manual
+`npm publish` step. The publish job re-runs the full check suite first, because a
+bot-opened pull request does not run CI until a maintainer approves it. After
+publishing, a smoke job installs the released version from the registry and
+imports every subpath
+(`npm run check:pack -- --from-registry=<version>`).
+
+See [`docs/domains/release.md`](docs/domains/release.md) for the flow and the
+one-time bootstrap that had to be done by hand.
+
+## Working with AI agents
+
+This repo uses a [lightweight spec-driven workflow](https://github.com/vitaliy-tkachuk/ai-spec-template). AI agents (Claude Code, Cursor, Codex, Copilot, Aider, etc.) follow the rules in [`AGENTS.md`](AGENTS.md).
+
+Key docs:
+
+- [`AGENTS.md`](AGENTS.md) — canonical instructions for AI agents
+- [`docs/feature-workflow.md`](docs/feature-workflow.md) — complexity levels (0–3) and required artifacts
+- [`docs/architecture.md`](docs/architecture.md) — system architecture
+- [`docs/coding-conventions.md`](docs/coding-conventions.md) — coding conventions
+- [`docs/patterns.md`](docs/patterns.md) — cross-domain reusable patterns
+- [`docs/domains/`](docs/domains/) — per-domain durable knowledge (the permanent record)
+
+Architectural decisions live in `docs/architecture.md`. Task files (`docs/tasks/`) are ephemeral, local-only, and gitignored.
+
+### Knowledge graph
+
+If `graphify-out/graph.json` is present, it is a committed [graphify](https://github.com/safishamsi/graphify) knowledge graph of this repo. Agents query it before reading files (`graphify query "<question>"`), which is far cheaper than sweeping the tree — see [`AGENTS.md`](AGENTS.md#knowledge-graph--query-it-first-to-save-tokens).
+
+The graph auto-rebuilds after each commit via local git hooks. Those hooks are not committed, so run `graphify hook install` once per clone. If the repo has no graph yet, build one with `/graphify .` and commit `graphify-out/`.

package/dist/core/book.d.ts

@@ -0,0 +1,75 @@
+/** A lazily loaded binary payload with its media type. */
+export interface Resource {
+    readonly mediaType: string;
+    load(): Promise<Uint8Array>;
+}
+/** Fields the format could not determine are omitted, never set to undefined. */
+export interface BookMetadata {
+    readonly title?: string;
+    readonly author?: string;
+    /** BCP 47 language tag. */
+    readonly language?: string;
+    readonly cover?: Resource;
+}
+/** A table-of-contents entry; targets a section by id, never by file path. */
+export interface TocItem {
+    readonly label: string;
+    readonly sectionId: string;
+    /** Anchor within the section, when the format provides one. */
+    readonly fragment?: string;
+    readonly children: readonly TocItem[];
+}
+/** One unit of the book's reading order. */
+export interface Section {
+    /** Unique within the book. */
+    readonly id: string;
+    readonly mediaType: string;
+    /** True when the content declares executable script; omitted when unknown. */
+    readonly scripted?: boolean;
+    load(): Promise<Uint8Array>;
+    /**
+     * Resolves a reference appearing inside this section's content — in whatever
+     * form the format uses — to the resource it names. Returns undefined when the
+     * reference names nothing this book can supply. Omitted by formats that
+     * cannot resolve references.
+     */
+    resolve?(reference: string): Resource | undefined;
+    /**
+     * Resolves a reference appearing inside this section's content to the *section*
+     * it targets (plus any fragment), or undefined when it names no section in this
+     * book. The counterpart to {@link resolve}: `resolve` hands back a `Resource`'s
+     * bytes for a reference (an image, a stylesheet), this hands back a navigation
+     * target for a reference to another reading unit — a "next chapter" link, a
+     * table-of-contents entry rendered in-content. Section-relative (a bare
+     * `chapter-2.xhtml` resolves against this section's own location) and path-free
+     * on return, so container paths never enter the model. Omitted by formats whose
+     * references cannot name a section (plain text has none).
+     */
+    resolveHref?(reference: string): SectionRef | undefined;
+}
+/**
+ * A resolved in-content reference: the section it targets, plus any fragment the
+ * reference carried. Path-free by design — the return names a section by id, never
+ * by container path, so paths never enter the model.
+ */
+export interface SectionRef {
+    readonly sectionId: string;
+    /** Anchor within the target section, when the reference carried one. */
+    readonly fragment?: string;
+}
+/** Reading order of the pages: left-to-right or right-to-left. */
+export type ReadingDirection = 'ltr' | 'rtl';
+export interface Book {
+    readonly metadata: BookMetadata;
+    readonly toc: readonly TocItem[];
+    /** Reading order. */
+    readonly sections: readonly Section[];
+    section(id: string): Section | undefined;
+    /** Non-section payloads (images, stylesheets) keyed by format-defined id. */
+    readonly resources: ReadonlyMap<string, Resource>;
+    /** Declared reading direction; omitted when the book does not declare one. */
+    readonly direction?: ReadingDirection;
+    /** True when the book declares fixed-size pages. Detection only — rendering stays reflowable. */
+    readonly fixedLayout?: boolean;
+}
+//# sourceMappingURL=book.d.ts.map

package/dist/core/book.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"book.d.ts","sourceRoot":"","sources":["../../src/core/book.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAClD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,KAAK,CAAC;AAE7C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;IACjC,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC"}

package/dist/core/book.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=book.js.map

package/dist/core/book.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"book.js","sourceRoot":"","sources":["../../src/core/book.ts"],"names":[],"mappings":""}

package/dist/core/errors.d.ts

@@ -0,0 +1,17 @@
+/** Base class for every error this library throws. */
+export declare class BookError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** No registered format claimed the input bytes. */
+export declare class UnrecognizedFormatError extends BookError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The container structure is damaged or malformed. */
+export declare class CorruptContainerError extends BookError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The content is encrypted; DRM-free books only. */
+export declare class EncryptedContentError extends BookError {
+    constructor(message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,qBAAa,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF;AAED,oDAAoD;AACpD,qBAAa,uBAAwB,SAAQ,SAAS;IACpD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF;AAED,uDAAuD;AACvD,qBAAa,qBAAsB,SAAQ,SAAS;IAClD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF;AAED,qDAAqD;AACrD,qBAAa,qBAAsB,SAAQ,SAAS;IAClD,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF"}

package/dist/core/errors.js

@@ -0,0 +1,29 @@
+/** Base class for every error this library throws. */
+export class BookError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'BookError';
+    }
+}
+/** No registered format claimed the input bytes. */
+export class UnrecognizedFormatError extends BookError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'UnrecognizedFormatError';
+    }
+}
+/** The container structure is damaged or malformed. */
+export class CorruptContainerError extends BookError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CorruptContainerError';
+    }
+}
+/** The content is encrypted; DRM-free books only. */
+export class EncryptedContentError extends BookError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'EncryptedContentError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,OAAO,uBAAwB,SAAQ,SAAS;IACpD,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,uDAAuD;AACvD,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAClD,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,qDAAqD;AACrD,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAClD,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/core/format.d.ts

@@ -0,0 +1,13 @@
+import type { Book } from './book.ts';
+import type { ByteSource } from './source.ts';
+import type { StorageAdapter } from './storage.ts';
+export interface FormatContext {
+    readonly storage?: StorageAdapter;
+}
+/** A registrable format: claims input via sniff, then decodes it to a Book. */
+export interface BookFormat {
+    readonly name: string;
+    sniff(source: ByteSource): boolean | Promise<boolean>;
+    decode(source: ByteSource, context: FormatContext): Promise<Book>;
+}
+//# sourceMappingURL=format.d.ts.map

package/dist/core/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE"}

package/dist/core/format.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format.js.map

package/dist/core/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":""}

package/dist/core/graphemes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared grapheme-boundary helper for the position layer (`src/core/position.ts`)
+ * and the paginator (`src/layout/index.ts`). Internal: nothing here is re-exported
+ * from `src/core/index.ts`, so it is not part of the frozen public surface.
+ *
+ * A segmented text is represented as a `Grapheme[]` whose `.index` values form a
+ * sorted array of UTF-16 code-unit boundaries; both offset↔index conversions are
+ * binary searches over that array. Segment once per text, convert O(log n) per
+ * call — never re-segment per lookup (the batch-capture invariant).
+ *
+ * Headless and pure `Intl.Segmenter`: grapheme segmentation is locale-independent,
+ * so one shared segmenter instance serves every caller.
+ */
+/** A grapheme cluster together with its UTF-16 code-unit offset in the text. */
+export interface Grapheme {
+    readonly segment: string;
+    readonly index: number;
+}
+/** Segments `text` into grapheme clusters, each keeping its code-unit index. */
+export declare function segmentGraphemes(text: string): Grapheme[];
+/** Number of grapheme clusters in `text`. */
+export declare function countGraphemes(text: string): number;
+/**
+ * Maps a UTF-16 offset to the grapheme index at or after it: the first index
+ * whose boundary is >= `offset`, or the grapheme count when `offset` is past
+ * every boundary. Binary search over the sorted `.index` boundaries.
+ */
+export declare function codeUnitOffsetToGraphemeIndex(graphemes: readonly Grapheme[], offset: number): number;
+/**
+ * Maps a grapheme index to its UTF-16 code-unit offset. An index at or past the
+ * end maps to `textLength` (the caller supplies it because a boundary array does
+ * not know where the final cluster ends). Exact for surrogate pairs, combining
+ * sequences, and emoji clusters, because each grapheme carries its real index.
+ */
+export declare function graphemeIndexToCodeUnitOffset(graphemes: readonly Grapheme[], textLength: number, graphemeIndex: number): number;
+//# sourceMappingURL=graphemes.d.ts.map

package/dist/core/graphemes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphemes.d.ts","sourceRoot":"","sources":["../../src/core/graphemes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAID,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMzD;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,MAAM,EAAE,MAAM,GACb,MAAM,CAUR;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,CAIR"}

package/dist/core/graphemes.js

@@ -0,0 +1,62 @@
+/**
+ * Shared grapheme-boundary helper for the position layer (`src/core/position.ts`)
+ * and the paginator (`src/layout/index.ts`). Internal: nothing here is re-exported
+ * from `src/core/index.ts`, so it is not part of the frozen public surface.
+ *
+ * A segmented text is represented as a `Grapheme[]` whose `.index` values form a
+ * sorted array of UTF-16 code-unit boundaries; both offset↔index conversions are
+ * binary searches over that array. Segment once per text, convert O(log n) per
+ * call — never re-segment per lookup (the batch-capture invariant).
+ *
+ * Headless and pure `Intl.Segmenter`: grapheme segmentation is locale-independent,
+ * so one shared segmenter instance serves every caller.
+ */
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** Segments `text` into grapheme clusters, each keeping its code-unit index. */
+export function segmentGraphemes(text) {
+    const out = [];
+    for (const segment of graphemeSegmenter.segment(text)) {
+        out.push({ segment: segment.segment, index: segment.index });
+    }
+    return out;
+}
+/** Number of grapheme clusters in `text`. */
+export function countGraphemes(text) {
+    let count = 0;
+    for (const _ of graphemeSegmenter.segment(text))
+        count += 1;
+    return count;
+}
+/**
+ * Maps a UTF-16 offset to the grapheme index at or after it: the first index
+ * whose boundary is >= `offset`, or the grapheme count when `offset` is past
+ * every boundary. Binary search over the sorted `.index` boundaries.
+ */
+export function codeUnitOffsetToGraphemeIndex(graphemes, offset) {
+    if (offset <= 0)
+        return 0;
+    let low = 0;
+    let high = graphemes.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (graphemes[mid].index >= offset)
+            high = mid;
+        else
+            low = mid + 1;
+    }
+    return low;
+}
+/**
+ * Maps a grapheme index to its UTF-16 code-unit offset. An index at or past the
+ * end maps to `textLength` (the caller supplies it because a boundary array does
+ * not know where the final cluster ends). Exact for surrogate pairs, combining
+ * sequences, and emoji clusters, because each grapheme carries its real index.
+ */
+export function graphemeIndexToCodeUnitOffset(graphemes, textLength, graphemeIndex) {
+    if (graphemeIndex <= 0)
+        return 0;
+    if (graphemeIndex >= graphemes.length)
+        return textLength;
+    return graphemes[graphemeIndex].index;
+}
+//# sourceMappingURL=graphemes.js.map

package/dist/core/graphemes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphemes.js","sourceRoot":"","sources":["../../src/core/graphemes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,iBAAiB,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;AAErF,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAA8B,EAC9B,MAAc;IAEd,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC;IAC5B,OAAO,GAAG,GAAG,IAAI,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,SAAS,CAAC,GAAG,CAAE,CAAC,KAAK,IAAI,MAAM;YAAE,IAAI,GAAG,GAAG,CAAC;;YAC3C,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAA8B,EAC9B,UAAkB,EAClB,aAAqB;IAErB,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,IAAI,aAAa,IAAI,SAAS,CAAC,MAAM;QAAE,OAAO,UAAU,CAAC;IACzD,OAAO,SAAS,CAAC,aAAa,CAAE,CAAC,KAAK,CAAC;AACzC,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,11 @@
+export type { Book, BookMetadata, ReadingDirection, Resource, Section, TocItem } from './book.ts';
+export { BookError, CorruptContainerError, EncryptedContentError, UnrecognizedFormatError, } from './errors.ts';
+export type { BookFormat, FormatContext } from './format.ts';
+export { open } from './open.ts';
+export { capturePosition, parsePosition, resolvePosition, segmentSentences, serializePosition, } from './position.ts';
+export type { CapturePositionOptions, Position, ResolvedPosition, SentenceRange, TextAnchor, } from './position.ts';
+export type { OpenOptions } from './open.ts';
+export { toByteSource } from './source.ts';
+export type { BookInput, ByteSource, RangeRead, RangeReader } from './source.ts';
+export type { StorageAdapter } from './storage.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAClG,OAAO,EACL,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,eAAe,EACf,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,6 @@
+/*! wolfy-reader v0.1.0 | @license MIT | (c) Vitaliy Tkachuk | github.com/vitaliy-tkachuk/wolfy-reader */
+export { BookError, CorruptContainerError, EncryptedContentError, UnrecognizedFormatError, } from './errors.js';
+export { open } from './open.js';
+export { capturePosition, parsePosition, resolvePosition, segmentSentences, serializePosition, } from './position.js';
+export { toByteSource } from './source.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";AACA,OAAO,EACL,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,eAAe,EACf,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/core/lookup.d.ts

@@ -0,0 +1,10 @@
+import type { Section } from './book.ts';
+/**
+ * A `Map`-backed `Book.section(id)` implementation shared by the decoders, so an
+ * id lookup is O(1) instead of a linear scan per call. First match wins on a
+ * duplicate id, matching the `Array.find` semantics it replaced (section ids are
+ * unique by the model's rules; this only pins the behavior if a decoder ever
+ * slips). Internal to the library — not re-exported from `src/core/index.ts`.
+ */
+export declare function sectionLookup(sections: readonly Section[]): (id: string) => Section | undefined;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/core/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/core/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,SAAS,CAM/F"}

package/dist/core/lookup.js

@@ -0,0 +1,16 @@
+/**
+ * A `Map`-backed `Book.section(id)` implementation shared by the decoders, so an
+ * id lookup is O(1) instead of a linear scan per call. First match wins on a
+ * duplicate id, matching the `Array.find` semantics it replaced (section ids are
+ * unique by the model's rules; this only pins the behavior if a decoder ever
+ * slips). Internal to the library — not re-exported from `src/core/index.ts`.
+ */
+export function sectionLookup(sections) {
+    const byId = new Map();
+    for (const section of sections) {
+        if (!byId.has(section.id))
+            byId.set(section.id, section);
+    }
+    return (id) => byId.get(id);
+}
+//# sourceMappingURL=lookup.js.map