@likecoin/epub-ts 0.5.0 → 0.6.0

package/README.md

@@ -1,30 +1,43 @@
 # epub.ts (`@likecoin/epub-ts`)
 
-A TypeScript fork of [epubjs](https://github.com/futurepress/epub.js) v0.3.93 by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress) — parse and render EPUB documents in the browser.
-
 [![CI](https://github.com/likecoin/epub.ts/actions/workflows/ci.yml/badge.svg)](https://github.com/likecoin/epub.ts/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40likecoin%2Fepub-ts)](https://www.npmjs.com/package/@likecoin/epub-ts)
 [![License](https://img.shields.io/npm/l/%40likecoin%2Fepub-ts)](./LICENSE)
 
-> **Note**: This library is primarily developed for internal use at [3ook.com](https://3ook.com) and is provided as-is. It was mainly built with AI-assisted development. For the original library, see [epubjs](https://github.com/futurepress/epub.js).
+**Drop-in replacement for [epubjs](https://github.com/futurepress/epub.js)** — same API, fully typed, 1 runtime dependency, actively maintained.
+
+A complete TypeScript rewrite of epubjs v0.3.93 with strict mode, modern tooling, and ongoing bug fixes — without breaking your existing code.
+
+## What you get
+
+- **Same API, zero migration cost** — change one import line and everything works
+- **Full TypeScript strict mode** — generated `.d.ts` from source, so autocomplete matches runtime
+- **1 runtime dependency** (`jszip`) — smaller bundle, simpler supply chain
+- **970+ tests** across 40 files — Vitest with robust coverage
+- **Vite build** — ESM, CJS, and UMD outputs out of the box
+- **Node.js support** — `@likecoin/epub-ts/node` parses EPUBs server-side with `linkedom`
+- **Active maintenance** — [20+ bug fixes](./CHANGELOG.md) and counting
 
-## Features
+> **Note**: Built at [3ook.com](https://3ook.com) and provided as-is. Forked from [epubjs](https://github.com/futurepress/epub.js) v0.3.93 by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress).
 
-- **Drop-in replacement** for epubjs v0.3.93 — same API, just change the import
-- **TypeScript first** — full strict mode, typed emitter, generated `.d.ts` declarations
-- **Modern build** — Vite library build, ESM + CJS output
-- **Fewer dependencies** — only 1 runtime dependency (`jszip`); removed `core-js`, `lodash`, `path-webpack`, `event-emitter`, `localforage`, `@xmldom/xmldom`
-- **Named exports** — import individual classes like `Book`, `EpubCFI`, `Rendition`, etc.
+## Get started
 
-## Installation
+### Install
 
 ```bash
 npm install @likecoin/epub-ts
 ```
 
-## Quick Start
+### Migrate from epubjs
+
+Change one line — everything else stays the same:
+
+```diff
+- import ePub from "epubjs";
++ import ePub from "@likecoin/epub-ts";
+```
 
-### ES Modules (recommended)
+### Render an EPUB (browser)
 
 ```typescript
 import ePub from "@likecoin/epub-ts";
@@ -34,7 +47,7 @@ const rendition = book.renderTo("viewer", { width: 600, height: 400 });
 rendition.display();
 ```
 
-### Browser (from ArrayBuffer)
+### Load from file input
 
 ```typescript
 import ePub from "@likecoin/epub-ts";
@@ -49,9 +62,9 @@ fileInput.addEventListener("change", async (event) => {
 });
 ```
 
-### Node.js (parsing only)
+### Parse on Node.js (no browser needed)
 
-Parse EPUB metadata, spine, navigation, and section content without a browser. Requires [`linkedom`](https://github.com/WebReflection/linkedom) as a peer dependency.
+Extract metadata, table of contents, and chapter HTML server-side. Requires [`linkedom`](https://github.com/WebReflection/linkedom):
 
 ```bash
 npm install linkedom
@@ -73,18 +86,7 @@ const section = book.spine.first();
 const html = await section.render(book.archive.request.bind(book.archive));
 ```
 
-## Migration from epubjs
-
-Drop-in replacement. Change your import:
-
-```diff
-- import ePub from "epubjs";
-+ import ePub from "@likecoin/epub-ts";
-```
-
-All APIs remain the same.
-
-## Named Exports
+## Named exports
 
 ```js
 import {
@@ -95,36 +97,21 @@ import {
 } from "@likecoin/epub-ts";
 ```
 
-## API
+## API reference
 
-See the full [API documentation](https://likecoin.github.io/epub.ts/) for details on all classes, interfaces, and methods.
+Full documentation: [likecoin.github.io/epub.ts](https://likecoin.github.io/epub.ts/)
 
-Key classes:
-
-| Class | Description |
+| Class | What it does |
 |-------|-------------|
-| `Book` | Main EPUB representation — loading, parsing, manipulation |
-| `Rendition` | Renders a book to a DOM element |
-| `Contents` | Manages content within an iframe |
-| `EpubCFI` | EPUB Canonical Fragment Identifier parser |
-| `Locations` | Generates and manages reading locations |
+| `Book` | Load, parse, and manipulate an EPUB |
+| `Rendition` | Render a book into a DOM element |
+| `Contents` | Manage content inside an iframe |
+| `EpubCFI` | Parse EPUB Canonical Fragment Identifiers |
+| `Locations` | Generate and query reading positions |
 | `Navigation` | Table of contents and landmarks |
 | `Annotations` | Highlights, underlines, and marks |
 
-## Comparison with epubjs
-
-| Aspect | epub.ts | epubjs |
-|--------|---------|--------|
-| Language | TypeScript (strict mode) | JavaScript |
-| Build | Vite | webpack + Babel |
-| Tests | Vitest | Karma + Mocha |
-| Type definitions | Generated from source | Hand-written `.d.ts` |
-| Dependencies | 1 (`jszip`) | 7+ (`core-js`, `lodash`, `event-emitter`, etc.) |
-| API compatibility | 100% (drop-in replacement) | — |
-| Bundle format | ESM + CJS + UMD | UMD |
-| Maintenance | Active | Inactive since 2022 |
-
-## Supported Environments
+## Supported environments
 
 | Environment | Import | Notes |
 |-------------|--------|-------|
@@ -132,48 +119,29 @@ Key classes:
 | Vite / webpack | `@likecoin/epub-ts` | ESM or CJS |
 | Node.js 18+ | `@likecoin/epub-ts/node` | Parsing only (no rendering); requires `linkedom` peer dep |
 
-## What's Changed from epubjs
-
-- Build: webpack + Babel → Vite
-- Tests: Karma + Mocha → Vitest
-- Source: JavaScript → TypeScript (full strict mode)
-- Removed dependencies: `core-js`, `lodash`, `path-webpack`, `localforage`, `@xmldom/xmldom`
-- Replaced `event-emitter` with inline typed emitter
-- Replaced `localforage` with native IndexedDB wrapper
-- Replaced `@xmldom/xmldom` with native DOMParser/XMLSerializer
-- Added Node.js parsing-only entry point (`@likecoin/epub-ts/node`) with `linkedom`
-- Dropped IE8–IE11 support
-
 ## Development
 
-### Prerequisites
-
-- Node.js 18+
-- npm 9+
-
-### Setup
-
 ```bash
 git clone https://github.com/likecoin/epub.ts.git
 cd epub.ts
 npm install
 ```
 
-### Scripts
-
 | Script | Description |
 |--------|-------------|
 | `npm run build` | Vite library build → `dist/` |
 | `npm test` | Run tests (Vitest) |
 | `npm run test:watch` | Run tests in watch mode |
-| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
+| `npm run typecheck` | `tsc --noEmit` |
 | `npm run lint` | ESLint |
 | `npm run lint:fix` | ESLint with auto-fix |
 | `npm run docs` | Generate API docs (HTML + Markdown) |
 
+Requires Node.js 18+ and npm 9+.
+
 ## Contributing
 
-See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for current conversion progress and what to work on.
+See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for current status and what to work on.
 
 For AI agents contributing to this project, see [AGENTS.md](./AGENTS.md).
 
@@ -186,11 +154,11 @@ For AI agents contributing to this project, see [AGENTS.md](./AGENTS.md).
 - [epubjs](https://github.com/futurepress/epub.js) by [Fred Chasen](https://github.com/fchasen) / [FuturePress](https://github.com/futurepress) — the original library this is forked from
 - [jszip](https://github.com/Stuk/jszip) — ZIP file handling
 
-## Built by 3ook.com
+## Built by [3ook.com](https://3ook.com)
 
-This project is built and maintained by the [3ook.com](https://3ook.com) team. 3ook is a Web3 eBook platform where authors can publish EPUB ebooks and readers can collect them as digital assets.
+3ook is a Web3 eBook platform where authors publish EPUB ebooks and readers collect them as digital assets.
 
-## Related Projects
+## Related projects
 
 - [epubjs](https://github.com/futurepress/epub.js) — Original EPUB reader library
 - [epubcheck-ts](https://github.com/likecoin/epubcheck-ts) — TypeScript EPUB validator (also by 3ook.com)

package/dist/annotations.d.ts

@@ -92,12 +92,10 @@ declare class Annotations {
     clear(view: AnnotationView): void;
     /**
      * [Not Implemented] Show annotations
-     * @TODO: needs implementation in View
      */
     show(): void;
     /**
      * [Not Implemented] Hide annotations
-     * @TODO: needs implementation in View
      */
     hide(): void;
 }
@@ -156,7 +154,6 @@ declare class Annotation implements IEventEmitter<AnnotationEvents> {
     detach(view: AnnotationView): void;
     /**
      * [Not Implemented] Get text of an annotation
-     * @TODO: needs implementation in contents
      */
     text(): void;
 }