@likecoin/epub-ts 0.3.96 → 0.4.0

package/README.md

@@ -2,9 +2,21 @@
 
 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.
 
-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.
+[![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)
 
-## Install
+> **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).
+
+## Features
+
+- **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.
+
+## Installation
 
 ```bash
 npm install @likecoin/epub-ts
@@ -12,18 +24,34 @@ npm install @likecoin/epub-ts
 
 ## Quick Start
 
-```js
+### ES Modules (recommended)
+
+```typescript
 import ePub from "@likecoin/epub-ts";
 
-// Same API as epubjs
 const book = ePub("/path/to/book.epub");
 const rendition = book.renderTo("viewer", { width: 600, height: 400 });
 rendition.display();
 ```
 
+### Browser (from ArrayBuffer)
+
+```typescript
+import ePub from "@likecoin/epub-ts";
+
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener("change", async (event) => {
+	const file = event.target.files[0];
+	const data = await file.arrayBuffer();
+	const book = ePub(data);
+	const rendition = book.renderTo("viewer", { width: 600, height: 400 });
+	rendition.display();
+});
+```
+
 ## Migration from epubjs
 
-This is a drop-in replacement. Change your import:
+Drop-in replacement. Change your import:
 
 ```diff
 - import ePub from "epubjs";
@@ -35,30 +63,110 @@ All APIs remain the same.
 ## Named Exports
 
 ```js
-import { Book, EpubCFI, Rendition, Contents, Layout } from "@likecoin/epub-ts";
+import {
+	Book, EpubCFI, Rendition, Contents, Layout,
+	Section, Spine, Locations, Navigation, PageList,
+	Resources, Packaging, Archive, Store,
+	Annotations, Themes, Mapping,
+} from "@likecoin/epub-ts";
 ```
 
-## What's Changed
+## API
+
+See the full [API documentation](https://likecoin.github.io/epub.ts/) for details on all classes, interfaces, and methods.
+
+Key classes:
+
+| Class | Description |
+|-------|-------------|
+| `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 |
+| `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 |
+| Maintenance | Active | Inactive since 2022 |
+
+## Supported Environments
+
+| Environment | Notes |
+|-------------|-------|
+| Modern browsers | Chrome, Firefox, Safari, Edge (requires DOM) |
+| Vite / webpack | ESM or CJS imports |
+
+> **Note**: This library requires a DOM environment. Node.js support (parsing-only, no rendering) is planned but not yet available.
+
+## What's Changed from epubjs
 
 - Build: webpack + Babel → Vite
 - Tests: Karma + Mocha → Vitest
-- Source: JavaScript → TypeScript (incremental conversion)
-- Removed dependencies: `core-js`, `lodash`, `path-webpack`
+- 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
+- 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
-npm run build     # Vite library build → dist/
-npm test          # Vitest
-npm run typecheck # tsc --noEmit
 ```
 
+### 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 lint` | ESLint |
+| `npm run lint:fix` | ESLint with auto-fix |
+| `npm run docs` | Generate API docs (HTML + Markdown) |
+
 ## Contributing
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for current conversion progress and what to work on.
 
+For AI agents contributing to this project, see [AGENTS.md](./AGENTS.md).
+
 ## License
 
-BSD-2-Clause (same as epubjs)
+[BSD-2-Clause](./LICENSE) (same as epubjs)
+
+## Acknowledgments
+
+- [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
+
+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.
+
+## 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/archive.d.ts

@@ -51,9 +51,9 @@ declare class Archive {
     getBlob(url: string, mimeType?: string): Promise<Blob> | undefined;
     /**
      * Get Text from Archive by Url
-     * @param  {string} url
-     * @param  {string} [encoding]
-     * @return {string}
+     * @param url
+     * @param _encoding
+     * @return text content
      */
     getText(url: string, _encoding?: string): Promise<string> | undefined;
     /**

package/dist/contents.d.ts

@@ -1,4 +1,5 @@
 import { default as EpubCFI } from './epubcfi';
+import { DOM_EVENTS } from './utils/constants';
 import { ViewportSettings, LayoutProps, EpubCFIPair, IEventEmitter } from './types';
 import { default as Section } from './section';
 /**
@@ -36,13 +37,18 @@ declare class Contents implements IEventEmitter {
     _resizeCheck: (() => void) | undefined;
     _triggerEvent: ((e: Event) => void) | undefined;
     _onSelectionChange: ((e: Event) => void) | undefined;
+    _onVisibilityChange: (() => void) | undefined;
+    _mediaQueryHandlers: {
+        mql: MediaQueryList;
+        handler: (e: MediaQueryListEvent) => void;
+    }[];
     selectionEndTimeout: ReturnType<typeof setTimeout> | undefined;
     _layoutStyle: string;
     constructor(doc: Document, content?: HTMLElement, cfiBase?: string, sectionIndex?: number);
     /**
         * Get DOM events that are listened for and passed along
         */
-    static get listenedEvents(): readonly ["keydown", "keyup", "keypressed", "mouseup", "mousedown", "mousemove", "click", "touchend", "touchstart", "touchmove"];
+    static get listenedEvents(): typeof DOM_EVENTS;
     /**
         * Get or Set width
         * @param {number} [w]
@@ -230,7 +236,7 @@ declare class Contents implements IEventEmitter {
     addClass(className: string): void;
     /**
      * Remove a class from the contents container
-     * @param {string} removeClass
+     * @param className - class name to remove
      */
     removeClass(className: string): void;
     /**
@@ -289,7 +295,6 @@ declare class Contents implements IEventEmitter {
      * @returns {EpubCFI} cfi
      */
     cfiFromNode(node: Node, ignoreClass?: string): string;
-    map(layout: LayoutProps): EpubCFIPair[];
     /**
      * Size the contents to a given width and height
      * @param {number} [width]